1LMISHELL(1) OpenLMI Tools LMISHELL(1)
2
6 lmishell - (non)interactive WBEM client and interpreter
7 OpenLMI Tools currently consist of LMIShell and the content of the doc‐
9 umentation itself is devoted to the LMIShell.
10
12 LMIShell provides a (non)interactive way how to access CIM objects pro‐
13 vided by OpenPegasus or sblim-sfcb broker.
14 Synopsis
16 lmishell [options] script [script-options]
17 Description
19 LMIShell provides a (non)interactive or interactive way how to access
20 CIM objects provided by OpenPegasus or sblim-sfcb CIMOM.
21 LMIShell is based on a python interpreter and added logic, therefore
23 what is possible to do in pure python, it is possible in LMIShell.
24 There are classes added to manipulate with CIM classes, instance names,
25 instances, etc. Additional classes are added to fulfill wrapper pat‐
26 tern and expose only those methods, which are necessary for the purpose
27 of a shell.
28 Options
30 The options may be given in any order before the first positional argu‐
31 ment, which stands for the script name.
32 -h, --help
34 Print summary of usage, command line options and exit.
35 -i, --interact
37 Enter interactive mode, when the script passed as the first
38 positional argument is executed.
39 -v, --verbose
41 Print log messages to stderr.
42 -m, --more-verbose
44 Print all log messages to stderr.
45 -q, --quiet
47 Do not print any log messages to stderr.
48 -n, --noverify
50 Do not verify server's certificate, if SSL used. By default,
51 the certificate validity check will be performed.
52 By default, LMIShell prints out log messages with Error severity.
54 Options -v, -m and -q are mutually exclusive and can not be used
55 together.
56 Startup
58 By running the following, you will gain an interactive interface of the
59 shell. The LMIShell is waiting for the end of an input to quit -- by
60 hitting <ctrl+d> you can exit from it:
61 $ lmishell
63 > <ctrl+d>
64 $
65 or:
67 $ lmishell
69 > quit()
70 $
71 Establish a connection
73 Following examples demonstrate, how to connect to a CIMOM by issuing a
74 connect() call.
75 Username/Password authentication
77 Common means of performing the authentication is done by providing a
78 username and password to connect() function. See the following example:
79 > c = connect("host", "username")
81 password: # <not echoed>
82 >
83 or:
85 > c = connect("host", "username", "password")
87 >
88 Certificate authentication
90 LMIShell is capable of creating a connection by using a X509 certifi‐
91 cate. For the purpose of creating a connection object, it is necessary
92 to provide two file names, which contain a certificate and a private
93 key.
94 See the following example:
96 > c = connect("host", key_file="key_file", cert_file="cert_file")
98 >
99 Unix socket
101 LMIShell can connect directly to the CIMOM using Unix socket. For this
102 type of connection, the shell needs to be run under root user and the
103 destination machine has to be either localhost, 127.0.0.1 or ::1. This
104 type of connection is supported by TOG-Pegasus and there needs to be a
105 Unix socket file present at /var/run/tog-pegasus/cimxml.socket. If the
106 condition is not met, classic username/password method will be used.
107 See following example:
109 > c = connect("localhost")
111 >
112 Credentials validation
114 Function connect() returns either LMIConnection object, if the connec‐
115 tion can be established, otherwise None is returned. Suppose, the
116 LMIShell is run in verbose mode (-v, --verbose, -m or --more-verbose is
117 used). See following example of creating a connection:
118 > # correct username or password
120 > c = connect("host", "username", "password")
121 INFO: Connected to host
122 > isinstance(c, LMIConnection)
123 True
124 > # wrong login username or password
125 > c = connect("host", "wrong_username", "wrong_password")
126 ERROR: Error connecting to host, <error message>
127 > c is None
128 True
129 >
130 NOTE: By default, LMIShell prints out only error messages, when calling
132 a connect(); no INFO messages will be print out. It is possible to sup‐
133 press all the messages by passing -q or --quiet).
134 Server's certificate validation
136 When using https transport protocol, LMIShell tries to validate each
137 server-side certificate against platform provided CA trust store. It is
138 necessary to copy the server's certificate from each CIMOM to the plat‐
139 form specific trust store directory.
140 NOTE: It is possible to make LMIShell skip the certificate validation
142 process by lmishell -n or --noverify.
143 See following example:
145 $ lmishell --noverify
147 >
148 Namespaces
150 Namespaces in CIM and LMIShell provide a natural way, how to organize
151 all the available classes and their instances. In the shell, they pro‐
152 vide a hierarchic access point to other namespaces and corresponding
153 classes.
154 The root namespace plays a special role in the managed system; it is
156 the first entry point from the connection object and provides the
157 access to other clamped namespaces.
158 Available namespaces
160 To get a LMINamespace object for the root namespace of the managed sys‐
161 tem, run following:
162 > root_namespace = c.root
164 >
165 To list all available namespace from the root one, run following code:
167 > c.root.print_namespaces()
169 ...
170 > ns_lst = c.root.namespaces
171 >
172 If you want to access any namespace deeper (e.g. cimv2), run this:
174 > cimv2_namespace = c.root.cimv2
176 > cimv2_namespace = c.get_namespace("root/cimv2")
177 >
178 Available classes
180 Each namespace object can print its available classes. To print/get the
181 list of the classes, run this:
182 > c.root.cimv2.print_classes()
184 ...
185 > classes_lst = c.root.cimv2.classes()
186 >
187 Queries
189 Using a LMINamespace object, it is possible to retrieve a list of LMI‐
190 Instance objects. The LMIShell supports 2 query languages:
191 · WQL
193 · CQL
195 Following code illustrates, how to execute WQL and CQL queries:
197 > instances_lst = namespace.wql("query")
199 > instances_lst = namespace.cql("query")
200 >
201 Classes
203 Each class in LMIShell represents a class provided by a CIMOM. You can
204 get a list of its properties, methods, instances, instance names and
205 ValueMap properties. It is also possible to print a documentation
206 string, create a new instance or new instance name.
207 Getting a class object
209 To get a class which is provided by a broker, you can do following:
210 > cls = c.root.cimv2.ClassName
212 >
213 Fetching a class
215 Objects of LMIClass use lazy fetching method, because some methods do
216 not need the CIMClass object.
217 To manually fetch the CIMClass object, call following:
219 > cls.fetch()
221 >
222 The methods, which need the CIMClass object to be fetched from CIMOM,
224 do this action automatically, without the need of calling LMI‐
225 Class.fetch() method by hand.
226 Class Methods
228 Following example illustrates, how to work with LMIClass methods:
229 > cls.print_methods()
231 ...
232 > cls_method_lst = cls.methods()
233 >
234 Class Properties
236 To get a list of properties of a specific class, run following code:
237 > cls.print_properties()
239 ...
240 > cls_property_lst = cls.properties()
241 >
242 Instances
244 Following part described basic work flow with LMIInstance and LMIIn‐
245 stanceName objects.
246 Get Instances
248 Using a class object, you can access its instances. You can easily get
249 a list of (filtered) instances, or the first one from the list. The
250 filtering is uses input dictionary, if present, where the dictionary
251 keys represent the instance properties and the dictionary values repre‐
252 sent your desired instance property values.
253 To get LMIInstance object, execute the following example:
255 > inst = cls.first_instance()
257 > inst_lst = cls.instances()
258 >
259 Get Instance Names
261 The CIMInstanceName objects clearly identify CIMInstance objects.
262 LMIShell can retrieve LMIInstanceName objects, by calling following:
263 > inst_name = cls.first_instance_name()
265 > inst_names_lst = cls.instance_names()
266 >
267 Filtering
269 Both methods LMIClass.instances() or LMIClass.instance_names() can fil‐
270 ter returned objects by their keys/values. The filtering is achieved by
271 passing a dictionary of {property : value} to the corresponding method.
272 See following example:
273 > inst_lst = cls.instances({"FilterProperty" : FilterValue})
275 > inst_names_lst = cls.instance_names({"FilterProperty" : FilterValue})
276 >
277 New Instance Name
279 LMIShell is able to create a new wrapped CIMInstanceName, if you know
280 all the primary keys of a remote object. This instance name object can
281 be then used to retrieve the whole instance object.
282 See the next example:
284 > inst_name = cls({Property1 : Value1, Property2 : Value2, ...})
286 > inst = inst_name.to_instance()
287 >
288 Creating a new instance
290 LMIShell is able to create an object of specific class, if the provider
291 support this operation.
292 See the following example:
294 > cls.create_instance({"Property1" : Value1, "Property2" : Value2})
296 >
297 NOTE: Value can be a LMIInstance object, as well. LMIShell will
299 auto-cast such object.
300 ValueMap Properties
302 A CIM class may contain ValueMap properties (aliases for constant val‐
303 ues) in its MOF definition. These properties contain constant values,
304 which can be useful, when calling a method, or checking a returned
305 value.
306 ValueMap properties are formed from 2 MOF properties of a class defini‐
308 tion:
309 · Values -- list of string names of the "constant" values
311 · ValueMap -- list of values
313 Get ValueMap properties
315 To get a list of all available constants, their values, use the follow‐
316 ing code:
317 > cls.print_valuemap_properties()
319 ...
320 > valuemap_properties = cls.valuemap_properties()
321 ...
322 > cls.PropertyValues.print_values()
323 ...
324 >
325 NOTE: The suffix "Values" provides a way, how to access ValueMap prop‐
327 erties.
328 Get ValueMap property value
330 Following example shows, how to retrieve a constant value:
331 > constant_value_names_lst = cls.PropertyValues.values()
333 > cls.PropertyValues.ConstantValueName
334 ConstantValue
335 > cls.PropertyValues.value("ConstantValueName")
336 ConstantValue
337 >
338 Get ValueMap property value name
340 LMIShell can also return string representing constant value. See the
341 following code:
342 > cls.PropertyValue.value_name(ConstantValue)
344 'ConstantValueName'
345 >
346 Useful Properties
348 Following part describes few useful LMIClass properties.
349 Class Name
351 Every class object can return a name of the CIM class, see following:
352 > cls.classname
354 ClassName
355 >
356 Namespace
358 Every class belongs to certain namespace, to get a string containing
359 the corresponding namespace for each class, run following:
360 > cls.namespace
362 Namespace
363 >
364 Connection Object
366 This property returns a connection object, which was used to retrieve
367 the class (refer to startup_connection). See next example:
368 > cls.connection
370 LMIConnection(URI='uri', user='user'...)
371 >
372 Wrapped Object
374 This property returns a wrapped pywbem object. See the example:
375 > instance.wrapped_object
377 CIMClass(u'ClassName', ...)
378 >
379 Documentation
381 To see a class documentation (based on MOF definitions), run:
382 > cls.doc()
384 # ... pretty verbose output displayed in a pages (can be modified by
385 # setting environment variable PAGER) ...
386 >
387 Instances
389 Each instance in LMIShell represents a CIM instance provided by a
390 CIMOM.
391 Operations, that can be done within a LMIInstance:
393 · get and set properties
395 · list/print/execute its methods
397 · print a documentation string
399 · get a list of associated objects
401 · get a list of association objects
403 · push (update) a modified object to CIMOM
405 · delete a single instance from the CIMOM.
407 Instance Methods
409 To get a list of methods, run following:
410 > instance.print_methods()
412 ...
413 > method_lst = instance.methods()
414 >
415 To execute a method within an object, run this:
417 > instance.Method(
419 ... {"Param1" : value1,
420 ... "Param2" : value2, ...})
421 LMIReturnValue(
422 rval=ReturnValue,
423 rparams=ReturnParametersDictionary,
424 errorstr="Possible error string"
425 )
426 >
427 NOTE: Instances do not auto-refresh after a method calls. It is neces‐
429 sary to perform this operation by hand (See instances_refreshing).
430 To get the result from a method call, see following:
432 > (rval, rparams, errorstr) = instance.Method(
434 ... {"Param1" : value1,
435 ... "Param2" : value2, ...})
436 >
437 The tuple in the previous example will contain return value of the
439 method call (rval), returned parameters (rparams) and possible error
440 string (errorstr).
441 Synchronous methods
443 LMIShell can perform synchronous method call, which means, that the
444 LMIShell is able to synchronously wait for a Job object to change its
445 state to Finished state and then return the job's return parameters.
446 LMIShell can perform the synchronous method call, if the given method
447 returns a object of following classes:
448 · LMI_StorageJob
450 · LMI_SoftwareInstallationJob
452 · LMI_SoftwareVerificationJob
454 · LMI_NetworkJob
456 LMIShell first tries to use indications as the waiting method. If it
458 fails, then it uses polling method instead.
459 Following example illustrates, how to perform a synchronous method
461 call:
462 > (rval, rparams, errorstr) = instance.SyncMethod(
464 ... {"Param1" : value1,
465 ... "Param2" : value2, ...})
466 >
467 NOTE: See the prefix Sync of a method name.
469 When a synchronous method call is done:
471 · rval will contain the job's return value
473 · rparams will contain the job's return parameters
475 · errorstr will contain job's possible error string
477 It is possible to force LMIShell to use only polling method, see the
479 next example:
480 > (rval, rparams, errorstr) = instance.SyncMethod(
482 ... {"Param1" : value1,
483 ... "Param2" : value2, ...},
484 ... PreferPolling=True)
485 >
486 Signal handling
488 LMIShell can properly handle SIGINT and SIGTERM, which instruct the
489 shell to cancel the synchronous call. When such signal is received, the
490 background job, for which the LMIShell is waiting, will be asked to
491 terminate, as well.
492 Instance Properties
494 To get a list of properties, see following:
495 > instance.print_properties()
497 ...
498 > instance_prop_lst = instance.properties()
499 >
500 It is possible to access an instance object properties. To get a prop‐
502 erty, see the following example:
503 > instance.Property
505 PropertyValue
506 >
507 To modify a property, execute following:
509 > instance.Property = NewPropertyValue
511 > instance.push()
512 LMIReturnValue(rval=0, rparams={}, errorstr="")
513 >
514 NOTE: If you change an instance object property, you have to execute a
516 LMIInstance.push() method to propagate the change to the CIMOM.
517 ValueMap Parameters
519 A CIM Method may contain ValueMap parameters (aliases for constant val‐
520 ues) in its MOF definition.
521 To access these parameters, which contain constant values, see follow‐
523 ing code:
524 > instance.Method.print_valuemap_parameters()
526 ...
527 > valuemap_parameters = instance.Method.valuemap_parameters()
528 >
529 Get ValueMap parameter value
531 By using a ValueMap parameters, you can retrieve a constant value
532 defined in the MOF file for a specific method.
533 To get a list of all available constants, their values, use the follow‐
535 ing code:
536 > instance.Method.ParameterValues.print_values()
538 ...
539 >
540 NOTE: The suffix Values provides a way, how to access ValueMap parame‐
542 ters.
543 To retrieve a constant value, see the next example:
545 > constant_value_names_lst = instance.Method.ParameterValues.values()
547 > instance.Method.ParameterValues.ConstantValueName
548 ConstantValue
549 > instance.Method.ParameterValues.value("ConstantValueName")
550 ConstantValue
551 >
552 Get ValueMap parameter
554 Method can also contain a mapping between constant property name and
555 corresponding value. Following code demonstrates, how to access such
556 parameters:
557 > instance.Method.ConstantValueName
559 >
560 Get ValueMap parameter value name
562 LMIShell can also return string representing constant value. See the
563 following code:
564 > instance.Method.ParameterValue.value_name(ConstantValue)
566 ConstantValueName
567 >
568 Instance refreshing
570 Local objects used by LMIShell, which represent CIM objects at CIMOM
571 side, can get outdated, if such object changes while working with
572 LMIShell's one.
573 To update object's properties, methods, etc. follow the next example:
575 > instance.refresh()
577 LMIReturnValue(rval=True, rparams={}, errorstr="")
578 >
579 Instance deletion
581 A single instance can be removed from the CIMOM by executing:
582 > instance.delete()
584 True
585 >
586 NOTE: After executing the LMIInstance.delete() method, all the object
588 properties, methods will become inaccessible.
589 Deletion of the instance can be verified by:
591 > instance.is_deleted
593 True
594 >
595 Documentation
597 For an instance object, you can also use a documentation method, which
598 will display verbose information of its properties and values.
599 See next example:
601 > instance.doc()
603 # ... pretty verbose output displayed in a pages (can be modified by
604 # setting environment variable PAGER) ...
605 >
606 MOF representation
608 An instance object can also print out its MOF representation. This can
609 be achieved by running:
610 > instance.tomof()
612 ... verbose output of the instance in MOF syntax ...
613 >
614 Useful Properties
616 Following part describes LMIInstance useful properties.
617 Class Name
619 Each instance object provide a property, that returns its class name.
620 To get a string of the class name, run following:
621 > instance.classname
623 ClassName
624 >
625 Namespace
627 Each instance object also provides a property, that returns a namespace
628 name. To get a string of the namespace name, run following:
629 > instance.namespace
631 Namespace
632 >
633 Path
635 To retrieve a unique, wrapped, identification object for the instance,
636 LMIInstanceName, execute following:
637 > instance.path
639 LMIInstanceName(classname="ClassName"...)
640 >
641 Connection Object
643 This property returns a connection object, which was used to retrieve
644 the instance (refer to startup_connection). See next example:
645 > instance.connection
647 LMIConnection(URI='uri', user='user'...)
648 >
649 Wrapped Object
651 This property returns a wrapped pywbem object. See the example:
652 > instance.wrapped_object
654 CIMInstance(classname=u'ClassName', ...)
655 >
656 Instance Names
658 LMIInstanceName is a object, which holds a set of primary keys and
659 their values. This type of object exactly identifies an instance.
660 Key properties
662 To get a list of key properties, see following example:
663 > instance_name.print_key_properties()
665 ...
666 > instance_name.key_properties()
667 ...
668 > instance_name.SomeKeyProperty
669 ...
670 >
671 Conversion to a LMIInstance
673 This type of object may be returned from a method call. Each instance
674 name can be converted into the instance, see next example:
675 > instance = instance_name.to_instance()
677 >
678 Useful Properties
680 Following part describes LMIInstanceName useful properties.
681 Class Name
683 The property returns a string representation of the class name. See
684 next example:
685 > instance_name.classname
687 ClassName
688 >
689 Namespace
691 The property returns a string representation of namesapce. See next
692 example:
693 > instance_name.namespace
695 Namespace
696 >
697 Host Name
699 This property returns a string representation of the host name, where
700 the CIM instance is located.
701 > instance_name.hostname
703 Hostname
704 >
705 Connection Object
707 This property returns a connection object, which was used to retrieve
708 the instance name (refer to startup_connection). See next example:
709 > instance.connection
711 LMIConnection(URI='uri', user='user'...)
712 >
713 Wrapped Object
715 This property returns a wrapped pywbem object. See the example:
716 > instance.wrapped_object
718 CIMInstanceName(classname=u'ClassName', keybindings=NocaseDict(...), host=u'hostname', namespace='namespace')
719 >
720 Associated Objects
722 CIM defines an association relationship between managed objects. Fol‐
723 lowing text describes the means of retrieving associated objects within
724 a given one.
725 Associated Instances
727 To get a list of associated LMIInstance objects with a given object,
728 run following:
729 > associated_objects = instance.associators(
731 ... AssocClass=cls,
732 ... ResultClass=cls,
733 ... ResultRole=role,
734 ... IncludeQualifiers=include_qualifiers,
735 ... IncludeClassOrigin=include_class_origin,
736 ... PropertyList=property_lst)
737 > first_associated_object = instance.first_associator(
738 ... AssocClass=cls,
739 ... ResultClass=cls,
740 ... ResultRole=role,
741 ... IncludeQualifiers=include_qualifiers,
742 ... IncludeClassOrigin=include_class_origin,
743 ... PropertyList=property_lst))
744 The list of returned associated objects can be filtered by:
746 · AssocClass -- Each returned object shall be associated to the source
748 object through an instance of this class or one of its subclasses.
749 Default value is None.
750 · ResultClass -- Each returned object shall be either an instance of
752 this class (or one of its subclasses) or be this class (or one of its
753 subclasses). Default value is None.
754 · Role -- Each returned object shall be associated with the source
756 object through an association in which the source object plays the
757 specified role. That is, the name of the property in the association
758 class that refers to the source object shall match the value of this
759 parameter. Default value is None.
760 · ResultRole -- Each returned object shall be associated to the source
762 object through an association in which the returned object plays the
763 specified role. That is, the name of the property in the association
764 class that refers to the returned object shall match the value of
765 this parameter. Default value is None.
766 Other parameters refer to:
768 · IncludeQualifiers -- Bool flag indicating, if all qualifiers for each
770 object (including qualifiers on the object and on any returned prop‐
771 erties) shall be included as <QUALIFIER> elements in the response.
772 Default value is False.
773 · IncludeClassOrigin -- Bool flag indicating, if the CLASSORIGIN
775 attribute shall be present on all appropriate elements in each
776 returned object. Default value is False.
777 · PropertyList -- The members of the array define one or more property
779 names. Each returned object shall not include elements for any prop‐
780 erties missing from this list. If PropertyList is an empty list, no
781 properties are included in each returned object. If it is None, no
782 additional filtering is defined. Default value is None.
783 Associated Instance Names
785 To get a list of associated LMIInstanceName objects with a given
786 object, run following:
787 > associated_object_names = instance.associator_names(
789 ... AssocClass=cls,
790 ... ResultClass=cls,
791 ... Role=role,
792 ... ResultRole=result_role)
793 > first_associated_object_name = instance.first_associator_name(
794 ... AssocClass=cls,
795 ... ResultClass=cls,
796 ... Role=role,
797 ... ResultRole=result_role)
798 >
799 The list of returned associated instance names can be filtered by:
801 · AssocClass -- Each returned name identify an object that shall be
803 associated to the source object through an instance of this class or
804 one of its subclasses. Default value is None.
805 · ResultClass -- Each returned name identify an object that shall be
807 either an instance of this class (or one of its subclasses) or be
808 this class (or one of its subclasses). Default value is None.
809 · Role -- Each returned name identify an object that shall be associ‐
811 ated to the source object through an association in which the source
812 object plays the specified role. That is, the name of the property in
813 the association class that refers to the source object shall match
814 the value of this parameter. Default value is None.
815 · ResultRole -- Each returned name identify an object that shall be
817 associated to the source object through an association in which the
818 named returned object plays the specified role. That is, the name of
819 the property in the association class that refers to the returned
820 object shall match the value of this parameter. Default value is
821 None.
822 Association Objects
824 CIM defines an association relationship between managed objects. Fol‐
825 lowing text describes the means of retrieving association objects
826 within a given one. An association object is the object, which defines
827 the relationship between two other objects.
828 Association Instances
830 To get association LMIInstance objects that refer to a particular tar‐
831 get object, run following:
832 > association_objects = instance.references(
834 ... ResultClass=cls,
835 ... Role=role,
836 ... IncludeQualifiers=include_qualifiers,
837 ... IncludeClassOrigin=include_class_origin,
838 ... PropertyList=property_lst)
839 > first_association_object = instance.first_reference(
840 ... ResultClass=cls,
841 ... Role=role,
842 ... IncludeQualifiers=include_qualifiers,
843 ... IncludeClassOrigin=include_class_origin,
844 ... PropertyList=property_lst)
845 >
846 The list of returned association objects can be filtered by:
848 · ResultClass -- Each returned object shall be an instance of this
850 class (or one of its subclasses) or this class (or one of its sub‐
851 classes). Default value is None.
852 · Role -- Each returned object shall refer to the target object through
854 a property with a name that matches the value of this parameter.
855 Default value is None.
856 Other parameters reffer to:
858 · IncludeQualifiers -- Each object (including qualifiers on the object
860 and on any returned properties) shall be included as <QUALIFIER> ele‐
861 ments in the response. Default value is False.
862 · IncludeClassOrigin -- Flag indicating, if the CLASSORIGIN attribute
864 shall be present on all appropriate elements in each returned object.
865 Default value is False.
866 · PropertyList -- The members of the list define one or more property
868 names. Each returned object shall not include elements for any prop‐
869 erties missing from this list. If PropertyList is an empty list, no
870 properties are included in each returned object. If PropertyList is
871 None, no additional filtering is defined. Default value is None.
872 Association Instance Names
874 To get a list of association LMIInstanceName objects, run following:
875 > association_object_names = instance.reference_names(
877 ... ResultClass=cls,
878 ... Role=role)
879 > first_association_object_name = instance.first_reference_name(
880 ... ResultClass=cls,
881 ... Role=role)
882 >
883 The list of returned association instance names can be filtered by:
885 · ResultClass -- Each returned Object Name identify an instance of this
887 class (or one of its subclasses) or this class (or one of its sub‐
888 classes). Default value is None.
889 · Role -- Each returned object name shall identify an object that
891 refers to the target instance through a property with a name that
892 matches the value of this parameter. Default value is None.
893 Indications
895 Indication is a reaction to some specific event that occurs in response
896 to a change to a particular change in data. LMIShell can perform a
897 indication subscription, by which we can receive such event responses.
898 Subscribing to an indication
900 The LMIShell is capable of creating an indication subscription with the
901 filter and handler objects in one single step. This example is based
902 upon sblim-cmpi-base provider.
903 How to subscribe to an indication, please, follow the next example:
905 > c = connect("host", "privileged_user", "password")
907 > c.subscribe_indication(
908 ... QueryLanguage="WQL",
909 ... Query='SELECT * FROM CIM_InstModification',
910 ... Name="cpu",
911 ... CreationNamespace="root/interop",
912 ... SubscriptionCreationClassName="CIM_IndicationSubscription",
913 ... FilterCreationClassName="CIM_IndicationFilter",
914 ... FilterSystemCreationClassName="CIM_ComputerSystem",
915 ... FilterSourceNamespace="root/cimv2",
916 ... HandlerCreationClassName="CIM_IndicationHandlerCIMXML",
917 ... HandlerSystemCreationClassName="CIM_ComputerSystem",
918 ... # destination computer, where the indications will be delivered
919 ... Destination="http://192.168.122.1:5988"
920 ... )
921 LMIReturnValue(rval=True, rparams={}, errorstr="")
922 >
923 The previous code can be simplified by omitting some optional parame‐
925 ters:
926 · QueryLanguage: DMTF:CQL
928 · CreationNamespace: root/interop
930 · SubscriptionCreationClassName: CIM_IndicationSubscription
932 · FilterCreationClassName: CIM_IndicationFilter
934 · FilterSystemCreationClassName: CIM_ComputerSystem
936 · FilterSourceNamespace: root/cimv2
938 · HandlerCreationClassName: CIM_IndicationHandlerCIMXML
940 · HandlerSystemCreationClassName: CIM_ComputerSystem
942 Simplified subscription:
944 > c = connect("host", "privileged_user", "password")
946 > c.subscribe_indication(
947 ... Name="cpu",
948 ... Query='SELECT * FROM CIM_InstModification',
949 ... Destination="http://192.168.122.1:5988"
950 ... )
951 LMIReturnValue(rval=True, rparams={}, errorstr="")
952 >
953 NOTE: Make sure, that you are logged-in with an account, which has
955 write privileges in the root/interop namespace.
956 In this state, we have a indication subscription created.
958 Auto-delete subscriptions
960 By default all subscriptions created by LMIShell will be auto-deleted,
961 when the shell quits. To change this behavior, you can pass Perma‐
962 nent=True keyword parameter to LMIConnection.subscribe_indication()
963 call, which will prevent LMIShell from deleting the subscription.
964 Listing subscribed indications
966 To list all the subscribed indications, run following code:
967 > c.print_subscribed_indications()
969 ...
970 > subscribed_ind_lst = c.subscribed_indications()
971 >
972 Unsubscribing from an indications
974 By default, the subscriptions created by the shell are auto-deleted,
975 when the shell quits.
976 If you want to delete the subscriptions sooner, you can use following
978 methods:
979 > c.unsubscribe_indication(indication_name)
981 LMIReturnValue(rval=True, rparams={}, errorstr="")
982 > c.unsubscribe_all_indications()
983 >
984 Indication handler
986 In the previous example, there is a local computer specified (the one,
987 which runs the shell), now we need to start a indication listener with
988 our indication handler function defined. This example continues (see
989 previous one). It is also possible to start another shell, script and
990 start the indication listener there.
991 See the following example:
993 > def handler(ind, arg1, arg2, **kwargs):
995 ... exported_objects = ind.exported_objects()
996 ... do_something_with(exported_objects)
997 > listener = LmiIndicationListener("0.0.0.0", listening_port)
998 > listener.add_handler("indication-name-XXXXXXXX", handler, arg1, arg2, **kwargs)
999 > listener.start()
1000 >
1001 The first argument of the handler is LMIIndication object, which con‐
1003 tains list of methods and objects exported by the indication. Other
1004 parameters are user specific; those arguments need to be specified,
1005 when adding a handler to the listener. In the example, there is a spe‐
1006 cial string used in the LMIIndicationListener.add_handler() call; note
1007 the eight "X" characters. Those characters will be replaced by random
1008 string, which is generated by the listeners to avoid handler name
1009 clash. If you want to use that random-based string, start indication
1010 listener first, then subscribe to an indication, so the Destination
1011 property of a handler object contains <schema>://<hostname>/<ran‐
1012 dom-based string>.
1013 Return Values
1015 Method calls return an object, that represents a return value of the
1016 given method. This type of object can be converted into python's typi‐
1017 cal 3-item tuple and consists of 3 items:
1018 · rval -- return value
1020 · rparams -- return value parameters
1022 · errorstr -- error string, if any
1024 Following example shows, how to use and convert LMIReturnValue object
1026 to tuple:
1027 > return_value = instance.MethodCall()
1029 > return_value.rval
1030 0
1031 > return_value.rparams
1032 []
1033 > return_value.errorstr
1034 > (rval, rparams, errorstr) = return_value
1036 > rval
1037 0
1038 > rparams
1039 []
1040 > errorstr
1041 >
1043 Interactive Interface
1045 This section covers some features, that are present in the interactive
1046 interface or are related to the LMIShell.
1047 History
1049 When using the interactive interface of the LMIShell, you can use
1050 up/down arrows to navigate in history of all the commands you previ‐
1051 ously used.
1052 Clearing the history
1054 If you want to clear the history, simply run:
1055 > clear_history()
1057 >
1058 Reversed search
1060 The LMIShell can also search in the history of commands by hitting
1061 <ctrl+r> and typing the command prefix (as your default shell does).
1062 See following:
1063 (reverse-i-search)'connect': c = connect("host", "username")
1065 Exception handling
1067 Exception handling by the shell can be turned off -- since then, all
1068 the exceptions need to be handled by your code. By default, LMIShell
1069 handles the exceptions and uses C-like return values (See section
1070 return_values) To allow all the exceptions to propagate to your code,
1071 run this:
1072 > use_exceptions()
1074 >
1075 To turn exception handling by the shell back on, run this:
1077 > use_exceptions(False)
1079 >
1080 Cache
1082 The LMIShell's connection objects use a temporary cache for storing CIM
1083 class names and CIM classes to save network communication.
1084 The cache can be cleared, see following example:
1086 > c.clear_cache()
1088 >
1089 The cache can be also turned off, see next example:
1091 > c.use_cache(False)
1093 >
1094 Tab-completion
1096 Interactive interface also supports tab-completion for basic program‐
1097 ming structures and also for CIM objects (such as namespace, classes,
1098 methods and properties completion, etc).
1099 Following code shows few examples:
1101 > c = conn<tab>
1103 > c = connect(
1104 > lmi_service_class = c.root.c<tab>
1106 > lmi_service_class = c.root.cimv2
1107 > lmi_service_class = c.root.cimv2.lmi_ser<tab>
1108 > lmi_service_class = c.root.cimv2.LMI_Service
1109 > sshd_service = lmi_s<tab>
1111 > sshd_service = lmi_service_class
1112 > sshd_service.Stat<tab>
1114 > sshd_service.Status
1115 > sshd_service.Res<tab>
1117 > sshd_service.RestartService(
1118 > lmi_service_class.Req<tab>
1120 > lmi_service_class.RequestedStateChangeValues
1121 > lmi_service_class.RequestesStateChangeValues.Sh<tab>
1122 > lmi_service_class.RequestedStateChangeValues.Shutdown
1123 > # similar for method calls, as well
1124 >
1125 Builtin features
1127 This section describes built-in features of the LMIShell.
1128 Configuration file
1130 The LMIShell has a tiny configuration file with location ~/.lmishellrc.
1131 In configuration file, you can set these properties:
1132 # location of the history used by interactive mode
1134 history_file = "~/.lmishell_history"
1135 # length of history file, -1 for unlimited
1136 history_length = -1
1137 # default value for cache usage
1138 use_cache = True
1139 # default value for exceptions
1140 use_exceptions = False
1141 Inspecting a script
1143 If you want to inspect a script after it has been interpreted by the
1144 LMIShell, run this:
1145 $ lmishell -i some_script.lmi
1147 # some stuff done
1148 >
1149 NOTE: Prefered extension of LMIShell's scripts is .lmi.
1151 LMI Is Instance
1153 LMIShell is able to verify, if a LMIInstance or LMIInstanceName object
1154 passed to lmi_isinstance() is a instance of LMIClass.
1155 The function is similar to python's isinstance():
1157 > lmi_isinstance(inst, cls)
1159 True/False
1160 >
1161 LMI Associators
1163 LMIShell can speed up associated objects' traversal by manual joining,
1164 instead of calling LMIInstance.associators(). The call needs to get a
1165 list of association classes, for which the referenced objects will be
1166 joined. The list must contain objects of LMIClass.
1167 See following example:
1169 > associators = lmi_associators(list_of_association_classes)
1171 >
1172
1174 Peter Hatina <phatina@redhat.com>
1175
1177 2012-2013, Red Hat Inc.
11780.9 June 09, 2014 LMISHELL(1)