LMISHELL(1) OpenLMI Tools LMISHELL(1)NAMElmishell - (non)interactive WBEM client and interpreter
OpenLMI Tools currently consist of LMIShell and the content of the doc‐
umentation itself is devoted to the LMIShell.
LMISHELL
LMIShell provides a (non)interactive way how to access CIM objects pro‐
vided by OpenPegasus or sblim-sfcb broker.
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 pat‐
tern 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 argu‐
ment, which stands for the script name.
-h, --help
Print summary of usage, command line options and exit.
-i, --interact
Enter interactive mode, when the script passed as the first
positional argument is executed.
-v, --verbose
Print log messages to stderr.
-m, --more-verbose
Print all log messages to stderr.
-q, --quiet
Do not print any log messages to stderr.
-n, --noverify
Do not verify server's certificate, if SSL used. By default,
the certificate validity check will be performed.
By default, LMIShell prints out log messages with Error severity.
Options -v, -m and -q are mutually exclusive and can not be used
together.
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 certifi‐
cate. 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 connec‐
tion 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 sup‐
press 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 plat‐
form 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 pro‐
vide 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 sys‐
tem, 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 LMI‐
Instance objects. The LMIShell supports 2 query languages:
· WQL
· CQL
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 LMI‐
Class.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 LMIIn‐
stanceName 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 repre‐
sent 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 fil‐
ter 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 val‐
ues) 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 defini‐
tion:
· Values -- list of string names of the "constant" values
· ValueMap -- list of values
Get ValueMap properties
To get a list of all available constants, their values, use the follow‐
ing 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 prop‐
erties.
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:
· get and set properties
· list/print/execute its methods
· print a documentation string
· get a list of associated objects
· get a list of association objects
· push (update) a modified object to CIMOM
· delete a single instance from the CIMOM.
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 neces‐
sary 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:
· LMI_StorageJob
· LMI_SoftwareInstallationJob
· LMI_SoftwareVerificationJob
· LMI_NetworkJob
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:
· rval will contain the job's return value
· rparams will contain the job's return parameters
· errorstr will contain job's possible error string
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 prop‐
erty, 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 val‐
ues) in its MOF definition.
To access these parameters, which contain constant values, see follow‐
ing 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 follow‐
ing code:
> instance.Method.ParameterValues.print_values()
...
>
NOTE: The suffix Values provides a way, how to access ValueMap parame‐
ters.
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. Fol‐
lowing 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:
· AssocClass -- Each returned object shall be associated to the source
object through an instance of this class or one of its subclasses.
Default value is None.
· ResultClass -- Each returned object shall be either an instance of
this class (or one of its subclasses) or be this class (or one of its
subclasses). Default value is None.
· Role -- Each returned object shall be associated with the source
object through an association in which the source object plays the
specified role. That is, the name of the property in the association
class that refers to the source object shall match the value of this
parameter. Default value is None.
· ResultRole -- Each returned object shall be associated to the source
object through an association in which the returned object plays the
specified role. That is, the name of the property in the association
class that refers to the returned object shall match the value of
this parameter. Default value is None.
Other parameters refer to:
· IncludeQualifiers -- Bool flag indicating, if all qualifiers for each
object (including qualifiers on the object and on any returned prop‐
erties) shall be included as <QUALIFIER> elements in the response.
Default value is False.
· IncludeClassOrigin -- Bool flag indicating, if the CLASSORIGIN
attribute shall be present on all appropriate elements in each
returned object. Default value is False.
· PropertyList -- The members of the array define one or more property
names. Each returned object shall not include elements for any prop‐
erties missing from this list. If PropertyList is an empty list, no
properties are included in each returned object. If it is None, no
additional filtering is defined. Default value is None.
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:
· AssocClass -- Each returned name identify an object that shall be
associated to the source object through an instance of this class or
one of its subclasses. Default value is None.
· ResultClass -- Each returned name identify an object that shall be
either an instance of this class (or one of its subclasses) or be
this class (or one of its subclasses). Default value is None.
· Role -- Each returned name identify an object that shall be associ‐
ated to the source object through an association in which the source
object plays the specified role. That is, the name of the property in
the association class that refers to the source object shall match
the value of this parameter. Default value is None.
· ResultRole -- Each returned name identify an object that shall be
associated to the source object through an association in which the
named returned object plays the specified role. That is, the name of
the property in the association class that refers to the returned
object shall match the value of this parameter. Default value is
None.
Association Objects
CIM defines an association relationship between managed objects. Fol‐
lowing 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 tar‐
get 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:
· ResultClass -- Each returned object shall be an instance of this
class (or one of its subclasses) or this class (or one of its sub‐
classes). Default value is None.
· Role -- Each returned object shall refer to the target object through
a property with a name that matches the value of this parameter.
Default value is None.
Other parameters reffer to:
· IncludeQualifiers -- Each object (including qualifiers on the object
and on any returned properties) shall be included as <QUALIFIER> ele‐
ments in the response. Default value is False.
· IncludeClassOrigin -- Flag indicating, if the CLASSORIGIN attribute
shall be present on all appropriate elements in each returned object.
Default value is False.
· PropertyList -- The members of the list define one or more property
names. Each returned object shall not include elements for any prop‐
erties missing from this list. If PropertyList is an empty list, no
properties are included in each returned object. If PropertyList is
None, no additional filtering is defined. Default value is None.
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:
· ResultClass -- Each returned Object Name identify an instance of this
class (or one of its subclasses) or this class (or one of its sub‐
classes). Default value is None.
· Role -- Each returned object name shall identify an object that
refers to the target instance through a property with a name that
matches the value of this parameter. Default value is None.
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 parame‐
ters:
· QueryLanguage: DMTF:CQL
· CreationNamespace: root/interop
· SubscriptionCreationClassName: CIM_IndicationSubscription
· FilterCreationClassName: CIM_IndicationFilter
· FilterSystemCreationClassName: CIM_ComputerSystem
· FilterSourceNamespace: root/cimv2
· HandlerCreationClassName: CIM_IndicationHandlerCIMXML
· HandlerSystemCreationClassName: CIM_ComputerSystem
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 Perma‐
nent=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 con‐
tains 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 spe‐
cial 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>/<ran‐
dom-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 typi‐
cal 3-item tuple and consists of 3 items:
· rval -- return value
· rparams -- return value parameters
· errorstr -- error string, if any
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 previ‐
ously 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 program‐
ming 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)
>
AUTHOR
Peter Hatina <phatina@redhat.com>
COPYRIGHT
2012-2013, Red Hat Inc.
0.9 May 06, 2014 LMISHELL(1)
