Synopsis¶

lmishell [options] script [script-options]

Description¶

LMIShell provides a (non)interactive or interactive way how to access CIM objects provided by OpenPegasus or sblim-sfcb CIMOM.

LMIShell is based on a python interpreter and added logic, therefore what is possible to do in pure python, it is possible in LMIShell. There are classes added to manipulate with CIM classes, instance names, instances, etc. Additional classes are added to fulfill wrapper pattern and expose only those methods, which are necessary for the purpose of a shell.

Options¶

The options may be given in any order before the first positional argument, which stands for the script name.

Startup¶

By running the following, you will gain an interactive interface of the shell. The LMIShell is waiting for the end of an input to quit -- by hitting <ctrl+d> you can exit from it:

$ lmishell
> <ctrl+d>
$

or:

$ lmishell
> quit()
$

Establish a connection¶

Following examples demonstrate, how to connect to a CIMOM by issuing a connect() call.

Username/Password authentication¶

Common means of performing the authentication is done by providing a username and password to connect() function. See the following example:

> c = connect("host", "username")
password: # <not echoed>
>

or:

> c = connect("host", "username", "password")
>

Certificate authentication¶

LMIShell is capable of creating a connection by using a X509 certificate. For the purpose of creating a connection object, it is necessary to provide two file names, which contain a certificate and a private key.

See the following example:

> c = connect("host", key_file="key_file", cert_file="cert_file")
>

Unix socket¶

LMIShell can connect directly to the CIMOM using Unix socket. For this type of connection, the shell needs to be run under root user and the destination machine has to be either localhost, 127.0.0.1 or ::1. This type of connection is supported by TOG-Pegasus and there needs to be a Unix socket file present at /var/run/tog-pegasus/cimxml.socket. If the condition is not met, classic username/password method will be used.

See following example:

> c = connect("localhost")
>

Credentials validation¶

Function connect() returns either LMIConnection object, if the connection can be established, otherwise None is returned. Suppose, the LMIShell is run in verbose mode (-v, --verbose, -m or --more-verbose is used). See following example of creating a connection:

> # correct username or password
> c = connect("host", "username", "password")
INFO: Connected to host
> isinstance(c, LMIConnection)
True
> # wrong login username or password
> c = connect("host", "wrong_username", "wrong_password")
ERROR: Error connecting to host, <error message>
> c is None
True
>

NOTE: By default, LMIShell prints out only error messages, when calling a connect(); no INFO messages will be print out. It is possible to suppress all the messages by passing -q or --quiet).

Server's certificate validation¶

When using https transport protocol, LMIShell tries to validate each server-side certificate against platform provided CA trust store. It is necessary to copy the server's certificate from each CIMOM to the platform specific trust store directory.

NOTE: It is possible to make LMIShell skip the certificate validation process by lmishell -n or --noverify.

See following example:

$ lmishell --noverify
>

Namespaces¶

Namespaces in CIM and LMIShell provide a natural way, how to organize all the available classes and their instances. In the shell, they provide a hierarchic access point to other namespaces and corresponding classes.

The root namespace plays a special role in the managed system; it is the first entry point from the connection object and provides the access to other clamped namespaces.

Available namespaces¶

To get a LMINamespace object for the root namespace of the managed system, run following:

> root_namespace = c.root
>

To list all available namespace from the root one, run following code:

> c.root.print_namespaces()
...
> ns_lst = c.root.namespaces
>

If you want to access any namespace deeper (e.g. cimv2), run this:

> cimv2_namespace = c.root.cimv2
> cimv2_namespace = c.get_namespace("root/cimv2")
>

Available classes¶

Each namespace object can print its available classes. To print/get the list of the classes, run this:

> c.root.cimv2.print_classes()
...
> classes_lst = c.root.cimv2.classes()
>

Queries¶

Using a LMINamespace object, it is possible to retrieve a list of LMIInstance objects. The LMIShell supports 2 query languages:

Following code illustrates, how to execute WQL and CQL queries:

> instances_lst = namespace.wql("query")
> instances_lst = namespace.cql("query")
>

Classes¶

Each class in LMIShell represents a class provided by a CIMOM. You can get a list of its properties, methods, instances, instance names and ValueMap properties. It is also possible to print a documentation string, create a new instance or new instance name.

Getting a class object¶

To get a class which is provided by a broker, you can do following:

> cls = c.root.cimv2.ClassName
>

Fetching a class¶

Objects of LMIClass use lazy fetching method, because some methods do not need the CIMClass object.

To manually fetch the CIMClass object, call following:

> cls.fetch()
>

The methods, which need the CIMClass object to be fetched from CIMOM, do this action automatically, without the need of calling LMIClass.fetch() method by hand.

Class Methods¶

Following example illustrates, how to work with LMIClass methods:

> cls.print_methods()
...
> cls_method_lst = cls.methods()
>

Class Properties¶

To get a list of properties of a specific class, run following code:

> cls.print_properties()
...
> cls_property_lst = cls.properties()
>

Instances¶

Following part described basic work flow with LMIInstance and LMIInstanceName objects.

Get Instances¶

Using a class object, you can access its instances. You can easily get a list of (filtered) instances, or the first one from the list. The filtering is uses input dictionary, if present, where the dictionary keys represent the instance properties and the dictionary values represent your desired instance property values.

To get LMIInstance object, execute the following example:

> inst = cls.first_instance()
> inst_lst = cls.instances()
>

Get Instance Names¶

The CIMInstanceName objects clearly identify CIMInstance objects. LMIShell can retrieve LMIInstanceName objects, by calling following:

> inst_name = cls.first_instance_name()
> inst_names_lst = cls.instance_names()
>

Filtering¶

Both methods LMIClass.instances() or LMIClass.instance_names() can filter returned objects by their keys/values. The filtering is achieved by passing a dictionary of {property : value} to the corresponding method. See following example:

> inst_lst = cls.instances({"FilterProperty" : FilterValue})
> inst_names_lst = cls.instance_names({"FilterProperty" : FilterValue})
>

New Instance Name¶

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

See the next example:

> inst_name = cls({Property1 : Value1, Property2 : Value2, ...})
> inst = inst_name.to_instance()
>

Creating a new instance¶

LMIShell is able to create an object of specific class, if the provider support this operation.

See the following example:

> cls.create_instance({"Property1" : Value1, "Property2" : Value2})
>

NOTE: Value can be a LMIInstance object, as well. LMIShell will auto-cast such object.

ValueMap Properties¶

A CIM class may contain ValueMap properties (aliases for constant values) in its MOF definition. These properties contain constant values, which can be useful, when calling a method, or checking a returned value.

ValueMap properties are formed from 2 MOF properties of a class definition:

Get ValueMap properties¶

To get a list of all available constants, their values, use the following code:

> cls.print_valuemap_properties()
...
> valuemap_properties = cls.valuemap_properties()
...
> cls.PropertyValues.print_values()
...
>

NOTE: The suffix "Values" provides a way, how to access ValueMap properties.

Get ValueMap property value¶

Following example shows, how to retrieve a constant value:

> constant_value_names_lst = cls.PropertyValues.values()
> cls.PropertyValues.ConstantValueName
ConstantValue
> cls.PropertyValues.value("ConstantValueName")
ConstantValue
>

Get ValueMap property value name¶

LMIShell can also return string representing constant value. See the following code:

> cls.PropertyValue.value_name(ConstantValue)
'ConstantValueName'
>

Useful Properties¶

Following part describes few useful LMIClass properties.

Class Name¶

Every class object can return a name of the CIM class, see following:

> cls.classname
ClassName
>

Namespace¶

Every class belongs to certain namespace, to get a string containing the corresponding namespace for each class, run following:

> cls.namespace
Namespace
>

Connection Object¶

This property returns a connection object, which was used to retrieve the class (refer to startup_connection). See next example:

> cls.connection
LMIConnection(URI='uri', user='user'...)
>

Wrapped Object¶

This property returns a wrapped pywbem object. See the example:

> instance.wrapped_object
CIMClass(u'ClassName', ...)
>

Documentation¶

To see a class documentation (based on MOF definitions), run:

> cls.doc()
# ... pretty verbose output displayed in a pages (can be modified by
#     setting environment variable PAGER) ...
>

Instances¶

Each instance in LMIShell represents a CIM instance provided by a CIMOM.

Operations, that can be done within a LMIInstance:

Instance Methods¶

To get a list of methods, run following:

> instance.print_methods()
...
> method_lst = instance.methods()
>

To execute a method within an object, run this:

> instance.Method(
...    {"Param1" : value1,
...     "Param2" : value2, ...})
LMIReturnValue(


    rval=ReturnValue,


    rparams=ReturnParametersDictionary,


    errorstr="Possible error string"
)
>

NOTE: Instances do not auto-refresh after a method calls. It is necessary to perform this operation by hand (See instances_refreshing).

To get the result from a method call, see following:

> (rval, rparams, errorstr) = instance.Method(
...    {"Param1" : value1,
...     "Param2" : value2, ...})
>

The tuple in the previous example will contain return value of the method call (rval), returned parameters (rparams) and possible error string (errorstr).

Synchronous methods¶

LMIShell can perform synchronous method call, which means, that the LMIShell is able to synchronously wait for a Job object to change its state to Finished state and then return the job's return parameters. LMIShell can perform the synchronous method call, if the given method returns a object of following classes:

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

Following example illustrates, how to perform a synchronous method call:

> (rval, rparams, errorstr) = instance.SyncMethod(
...    {"Param1" : value1,
...     "Param2" : value2, ...})
>

NOTE: See the prefix Sync of a method name.

When a synchronous method call is done:

It is possible to force LMIShell to use only polling method, see the next example:

> (rval, rparams, errorstr) = instance.SyncMethod(
...    {"Param1" : value1,
...     "Param2" : value2, ...},
...    PreferPolling=True)
>

Signal handling¶

LMIShell can properly handle SIGINT and SIGTERM, which instruct the shell to cancel the synchronous call. When such signal is received, the background job, for which the LMIShell is waiting, will be asked to terminate, as well.

Instance Properties¶

To get a list of properties, see following:

> instance.print_properties()
...
> instance_prop_lst = instance.properties()
>

It is possible to access an instance object properties. To get a property, see the following example:

> instance.Property
PropertyValue
>

To modify a property, execute following:

> instance.Property = NewPropertyValue
> instance.push()
LMIReturnValue(rval=0, rparams={}, errorstr="")
>

NOTE: If you change an instance object property, you have to execute a LMIInstance.push() method to propagate the change to the CIMOM.

ValueMap Parameters¶

A CIM Method may contain ValueMap parameters (aliases for constant values) in its MOF definition.

To access these parameters, which contain constant values, see following code:

> instance.Method.print_valuemap_parameters()
...
> valuemap_parameters = instance.Method.valuemap_parameters()
>

Get ValueMap parameter value¶

By using a ValueMap parameters, you can retrieve a constant value defined in the MOF file for a specific method.

To get a list of all available constants, their values, use the following code:

> instance.Method.ParameterValues.print_values()
...
>

NOTE: The suffix Values provides a way, how to access ValueMap parameters.

To retrieve a constant value, see the next example:

> constant_value_names_lst = instance.Method.ParameterValues.values()
> instance.Method.ParameterValues.ConstantValueName
ConstantValue
> instance.Method.ParameterValues.value("ConstantValueName")
ConstantValue
>

Get ValueMap parameter¶

Method can also contain a mapping between constant property name and corresponding value. Following code demonstrates, how to access such parameters:

> instance.Method.ConstantValueName
>

Get ValueMap parameter value name¶

LMIShell can also return string representing constant value. See the following code:

> instance.Method.ParameterValue.value_name(ConstantValue)
ConstantValueName
>

Instance refreshing¶

Local objects used by LMIShell, which represent CIM objects at CIMOM side, can get outdated, if such object changes while working with LMIShell's one.

To update object's properties, methods, etc. follow the next example:

> instance.refresh()
LMIReturnValue(rval=True, rparams={}, errorstr="")
>

Instance deletion¶

A single instance can be removed from the CIMOM by executing:

> instance.delete()
True
>

NOTE: After executing the LMIInstance.delete() method, all the object properties, methods will become inaccessible.

Deletion of the instance can be verified by:

> instance.is_deleted
True
>

Documentation¶

For an instance object, you can also use a documentation method, which will display verbose information of its properties and values.

See next example:

> instance.doc()
# ... pretty verbose output displayed in a pages (can be modified by
#     setting environment variable PAGER) ...
>

MOF representation¶

An instance object can also print out its MOF representation. This can be achieved by running:

> instance.tomof()
... verbose output of the instance in MOF syntax ...
>

Useful Properties¶

Following part describes LMIInstance useful properties.

Class Name¶

Each instance object provide a property, that returns its class name. To get a string of the class name, run following:

> instance.classname
ClassName
>

Namespace¶

Each instance object also provides a property, that returns a namespace name. To get a string of the namespace name, run following:

> instance.namespace
Namespace
>

Path¶

To retrieve a unique, wrapped, identification object for the instance, LMIInstanceName, execute following:

> instance.path
LMIInstanceName(classname="ClassName"...)
>

Connection Object¶

This property returns a connection object, which was used to retrieve the instance (refer to startup_connection). See next example:

> instance.connection
LMIConnection(URI='uri', user='user'...)
>

Wrapped Object¶

This property returns a wrapped pywbem object. See the example:

> instance.wrapped_object
CIMInstance(classname=u'ClassName', ...)
>

Instance Names¶

LMIInstanceName is a object, which holds a set of primary keys and their values. This type of object exactly identifies an instance.

Key properties¶

To get a list of key properties, see following example:

> instance_name.print_key_properties()
...
> instance_name.key_properties()
...
> instance_name.SomeKeyProperty
...
>

Conversion to a LMIInstance¶

This type of object may be returned from a method call. Each instance name can be converted into the instance, see next example:

> instance = instance_name.to_instance()
>

Useful Properties¶

Following part describes LMIInstanceName useful properties.

Class Name¶

The property returns a string representation of the class name. See next example:

> instance_name.classname
ClassName
>

Namespace¶

The property returns a string representation of namesapce. See next example:

> instance_name.namespace
Namespace
>

Host Name¶

This property returns a string representation of the host name, where the CIM instance is located.

> instance_name.hostname
Hostname
>

Connection Object¶

This property returns a connection object, which was used to retrieve the instance name (refer to startup_connection). See next example:

> instance.connection
LMIConnection(URI='uri', user='user'...)
>

Wrapped Object¶

This property returns a wrapped pywbem object. See the example:

> instance.wrapped_object
CIMInstanceName(classname=u'ClassName', keybindings=NocaseDict(...), host=u'hostname', namespace='namespace')
>

Associated Objects¶

CIM defines an association relationship between managed objects. Following text describes the means of retrieving associated objects within a given one.

Associated Instances¶

To get a list of associated LMIInstance objects with a given object, run following:

> associated_objects = instance.associators(
...    AssocClass=cls,
...    ResultClass=cls,
...    ResultRole=role,
...    IncludeQualifiers=include_qualifiers,
...    IncludeClassOrigin=include_class_origin,
...    PropertyList=property_lst)
> first_associated_object = instance.first_associator(
...    AssocClass=cls,
...    ResultClass=cls,
...    ResultRole=role,
...    IncludeQualifiers=include_qualifiers,
...    IncludeClassOrigin=include_class_origin,
...    PropertyList=property_lst))

The list of returned associated objects can be filtered by:

Other parameters refer to:

Associated Instance Names¶

To get a list of associated LMIInstanceName objects with a given object, run following:

> associated_object_names = instance.associator_names(
...    AssocClass=cls,
...    ResultClass=cls,
...    Role=role,
...    ResultRole=result_role)
> first_associated_object_name = instance.first_associator_name(
...    AssocClass=cls,
...    ResultClass=cls,
...    Role=role,
...    ResultRole=result_role)
>

The list of returned associated instance names can be filtered by:

Association Objects¶

CIM defines an association relationship between managed objects. Following text describes the means of retrieving association objects within a given one. An association object is the object, which defines the relationship between two other objects.

Association Instances¶

To get association LMIInstance objects that refer to a particular target object, run following:

> association_objects = instance.references(
...    ResultClass=cls,
...    Role=role,
...    IncludeQualifiers=include_qualifiers,
...    IncludeClassOrigin=include_class_origin,
...    PropertyList=property_lst)
> first_association_object = instance.first_reference(
...    ResultClass=cls,
...    Role=role,
...    IncludeQualifiers=include_qualifiers,
...    IncludeClassOrigin=include_class_origin,
...    PropertyList=property_lst)
>

The list of returned association objects can be filtered by:

Other parameters reffer to:

Association Instance Names¶

To get a list of association LMIInstanceName objects, run following:

> association_object_names = instance.reference_names(
...    ResultClass=cls,
...    Role=role)
> first_association_object_name = instance.first_reference_name(
...    ResultClass=cls,
...    Role=role)
>

The list of returned association instance names can be filtered by:

Indications¶

Indication is a reaction to some specific event that occurs in response to a change to a particular change in data. LMIShell can perform a indication subscription, by which we can receive such event responses.

Subscribing to an indication¶

The LMIShell is capable of creating an indication subscription with the filter and handler objects in one single step. This example is based upon sblim-cmpi-base provider.

How to subscribe to an indication, please, follow the next example:

> c = connect("host", "privileged_user", "password")
> 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 computer, where the indications will be delivered
...    Destination="http://192.168.122.1:5988"
...  )
LMIReturnValue(rval=True, rparams={}, errorstr="")
>

The previous code can be simplified by omitting some optional parameters:

Simplified subscription:

> c = connect("host", "privileged_user", "password")
> c.subscribe_indication(
...    Name="cpu",
...    Query='SELECT * FROM CIM_InstModification',
...    Destination="http://192.168.122.1:5988"
...  )
LMIReturnValue(rval=True, rparams={}, errorstr="")
>

NOTE: Make sure, that you are logged-in with an account, which has write privileges in the root/interop namespace.

In this state, we have a indication subscription created.

Auto-delete subscriptions¶

By default all subscriptions created by LMIShell will be auto-deleted, when the shell quits. To change this behavior, you can pass Permanent=True keyword parameter to LMIConnection.subscribe_indication() call, which will prevent LMIShell from deleting the subscription.

Listing subscribed indications¶

To list all the subscribed indications, run following code:

> c.print_subscribed_indications()
...
> subscribed_ind_lst = c.subscribed_indications()
>

Unsubscribing from an indications¶

By default, the subscriptions created by the shell are auto-deleted, when the shell quits.

If you want to delete the subscriptions sooner, you can use following methods:

> c.unsubscribe_indication(indication_name)
LMIReturnValue(rval=True, rparams={}, errorstr="")
> c.unsubscribe_all_indications()
>

Indication handler¶

In the previous example, there is a local computer specified (the one, which runs the shell), now we need to start a indication listener with our indication handler function defined. This example continues (see previous one). It is also possible to start another shell, script and start the indication listener there.

See the following example:

> 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 LMIIndication object, which contains 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, there is a special string used in the LMIIndicationListener.add_handler() call; note the eight "X" characters. Those characters will be replaced by random string, which is generated by the listeners to avoid handler name clash. If you want to use that random-based string, start indication listener first, then subscribe to an indication, so the Destination property of a handler object contains <schema>://<hostname>/<random-based string>.

Return Values¶

Method calls return an object, that represents a return value of the given method. This type of object can be converted into python's typical 3-item tuple and consists of 3 items:

Following example shows, how to use and convert LMIReturnValue object to tuple:

> return_value = instance.MethodCall()
> return_value.rval
0
> return_value.rparams
[]
> return_value.errorstr
> (rval, rparams, errorstr) = return_value
> rval
0
> rparams
[]
> errorstr
>

Interactive Interface¶

This section covers some features, that are present in the interactive interface or are related to the LMIShell.

History¶

When using the interactive interface of the LMIShell, you can use up/down arrows to navigate in history of all the commands you previously used.

Clearing the history¶

If you want to clear the history, simply run:

> clear_history()
>

Reversed search¶

The LMIShell can also search in the history of commands by hitting <ctrl+r> and typing the command prefix (as your default shell does). See following:

(reverse-i-search)'connect': c = connect("host", "username")

Exception handling¶

Exception handling by the shell can be turned off -- since then, all the exceptions need to be handled by your code. By default, LMIShell handles the exceptions and uses C-like return values (See section return_values) To allow all the exceptions to propagate to your code, run this:

> use_exceptions()
>

To turn exception handling by the shell back on, run this:

> use_exceptions(False)
>

Cache¶

The LMIShell's connection objects use a temporary cache for storing CIM class names and CIM classes to save network communication.

The cache can be cleared, see following example:

> c.clear_cache()
>

The cache can be also turned off, see next example:

> c.use_cache(False)
>

Tab-completion¶

Interactive interface also supports tab-completion for basic programming structures and also for CIM objects (such as namespace, classes, methods and properties completion, etc).

Following code shows few examples:

> c = conn<tab>
> c = connect(
> lmi_service_class = c.root.c<tab>
> lmi_service_class = c.root.cimv2
> lmi_service_class = c.root.cimv2.lmi_ser<tab>
> lmi_service_class = c.root.cimv2.LMI_Service
> sshd_service = lmi_s<tab>
> sshd_service = lmi_service_class
> sshd_service.Stat<tab>
> sshd_service.Status
> sshd_service.Res<tab>
> sshd_service.RestartService(
> lmi_service_class.Req<tab>
> lmi_service_class.RequestedStateChangeValues
> lmi_service_class.RequestesStateChangeValues.Sh<tab>
> lmi_service_class.RequestedStateChangeValues.Shutdown
> # similar for method calls, as well
>

Builtin features¶

This section describes built-in features of the LMIShell.

Configuration file¶

The LMIShell has a tiny configuration file with location ~/.lmishellrc. In configuration file, you can set these properties:

# location of the history used by interactive mode
history_file = "~/.lmishell_history"
# length of history file, -1 for unlimited
history_length = -1
# default value for cache usage
use_cache = True
# default value for exceptions
use_exceptions = False

Inspecting a script¶

If you want to inspect a script after it has been interpreted by the LMIShell, run this:

$ lmishell -i some_script.lmi
# some stuff done
>

NOTE: Prefered extension of LMIShell's scripts is .lmi.

LMI Is Instance¶

LMIShell is able to verify, if a LMIInstance or LMIInstanceName object passed to lmi_isinstance() is a instance of LMIClass.

The function is similar to python's isinstance():

> lmi_isinstance(inst, cls)
True/False
>

LMI Associators¶

LMIShell can speed up associated objects' traversal by manual joining, instead of calling LMIInstance.associators(). The call needs to get a list of association classes, for which the referenced objects will be joined. The list must contain objects of LMIClass.

See following example:

> associators = lmi_associators(list_of_association_classes)
>