5. WBEM indication API¶
The WBEM indication API supports subscription for and receiving of CIM indications.
This chapter has the following sections:
- WBEMListener - The
WBEMListener
class provides a thread-based WBEM listener service for receiving indications. - WBEMSubscriptionManager - The
WBEMSubscriptionManager
class provides for managing subscriptions for indications.
Note
At this point, the WBEM indication API is experimental.
5.1. WBEMListener¶
The WBEMListener
class provides a thread-based WBEM listener
service that can receive CIM indications from multiple WBEM servers and that
calls registered callback functions to deliver the received indications.
5.1.1. Examples¶
The following example creates and runs a listener:
import sys
import logging
from socket import getfqdn
from pywbem import WBEMListener
def process_indication(indication, host):
'''This function gets called when an indication is received.'''
print("Received CIM indication from {host}: {ind!r}". \
format(host=host, ind=indication))
def main():
logging.basicConfig(stream=sys.stderr, level=logging.WARNING,
format='%(asctime)s - %(levelname)s - %(message)s)
certkeyfile = 'listener.pem'
url1 = 'http://server1'
conn1 = WBEMConnection(url1)
server1 = WBEMServer(conn1)
server1.determine_interop_ns()
url2 = 'http://server2'
conn2 = WBEMConnection(url2)
server2 = WBEMServer(conn2)
server2.validate_interop_ns('root/PG_InterOp')
my_listener = WBEMListener(host=getfqdn()
http_port=5988,
https_port=5989,
certfile=certkeyfile,
keyfile=certkeyfile)
my_listener.add_callback(process_indication)
listener.start()
# listener runs until executable terminated
# or listener.stop()
See the example in section WBEMSubscriptionManager for an example of using a listener in combination with a subscription manager.
Another listener example is in the script examples/listen.py
(when you
clone the GitHub pywbem/pywbem project). It is an interactive Python shell that
creates a listener and displays any indications it receives, in MOF format.
-
class
pywbem.
WBEMListener
(host, http_port=None, https_port=None, certfile=None, keyfile=None)[source]¶ A WBEM listener.
The listener supports starting and stopping threads that listen for CIM-XML ExportIndication messages using HTTP and/or HTTPS, and that pass any received indications on to registered callback functions.
Parameters: - host (string) – IP address or host name this listener can be reached at.
- http_port (string or integer) –
HTTP port this listener can be reached at. Note that at least one port (HTTP or HTTPS) must be set
None means not to set up a port for HTTP.
- https_port (string or integer) –
HTTPS port this listener can be reached at.
None means not to set up a port for HTTPS.
- certfile (string) –
File path of certificate file to be used as server certificate during SSL/TLS handshake when creating the secure HTTPS connection.
It is valid for the certificate file to contain a private key; the server certificate sent during SSL/TLS handshake is sent without the private key.
None means not to use a server certificate file. Setting up a port for HTTPS requires specifying a certificate file.
- keyfile (string) –
File path of private key file to be used by the server during SSL/TLS handshake when creating the secure HTTPS connection.
It is valid to specify a certificate file that contains a private key.
None means not to use a private key file. Setting up a port for HTTPS requires specifying a private key file.
-
__repr__
()[source]¶ Return a representation of the
WBEMListener
object with all attributes, that is suitable for debugging.
-
http_port
¶ The HTTP port this listener can be reached at, as an integer.
None means there is no port set up for HTTP.
-
https_port
¶ The HTTPS port this listener can be reached at, as an integer.
None means there is no port set up for HTTPS.
-
certfile
¶ The file path of the certificate file used as server certificate during SSL/TLS handshake when creating the secure HTTPS connection.
None means there is no certificate file being used (that is, no port is set up for HTTPS).
-
keyfile
¶ The file path of the private key file used by the server during SSL/TLS handshake when creating the secure HTTPS connection.
None means there is no certificate file being used (that is, no port is set up for HTTPS).
-
logger
¶ The logger object for this listener.
Each listener object has its own separate logger object that is created via
logging.getLogger()
.The name of this logger object is:
pywbem.listener.{id}
where
{id}
is theid()
value of the listener object. Users of the listener should not look up the logger object by name, but should use this property to get to it.By default, this logger uses the
NullHandler
log handler, and its log level islogging.NOTSET
. This causes this logger not to emit any log messages and to propagate them to the Python root logger.The behavior of this logger can be changed by invoking its methods (see
logging.Logger
). The behavior of the root logger can for example be configured usinglogging.basicConfig()
:import sys import logging logging.basicConfig(stream=sys.stderr, level=logging.WARNING, format='%(asctime)s - %(levelname)s - %(message)s')
-
start
()[source]¶ Start the WBEM listener threads, if they are not yet running.
A thread serving CIM-XML over HTTP is started if an HTTP port was specified for the listener. A thread serving CIM-XML over HTTPS is started if an HTTPS port was specified for the listener.
These server threads will handle the ExportIndication export message described in DSP0200 and they will invoke the registered callback functions for any received CIM indications.
These server threads can be stopped using the
stop()
method. They will be automatically stopped when the main thread terminates.
-
deliver_indication
(indication, host)[source]¶ This function is called by the listener threads for each received indication. It is not supposed to be called by the user.
It delivers the indication to all callback functions that have been added to the listener.
If a callback function raises any exception this is logged as an error using the listener logger and the next registered callback function is called.
Parameters: - indication (
CIMInstance
) – Representation of the CIM indication to be delivered. - host (string) – Host name or IP address of WBEM server sending the indication.
- indication (
-
add_callback
(callback)[source]¶ Add a callback function to the listener.
The callback function will be called for each indication this listener receives from any WBEM server.
If the callback function is already known to the listener, it will not be added.
Parameters: callback ( callback_interface()
) – Callable that is being called for each CIM indication that is received while the listener threads are running.
-
pywbem.
callback_interface
(indication, host)[source]¶ Interface of a callback function that is provided by the user of the API and that will be called by the listener for each received CIM indication.
Parameters: - indication (
CIMInstance
) – Representation of the CIM indication that has been received. Its path attribute is None. - host (string) – Host name or IP address of WBEM server sending the indication.
Raises: Exception
– If a callback function raises any exception this is logged as an error using the listener logger and the next registered callback function is called.- indication (
5.2. WBEMSubscriptionManager¶
The WBEMSubscriptionManager
class is a subscription manager
that provides for creating and removing indication subscriptions (including
indication filters and listener destinations) for multiple WBEM servers and
multiple WBEM listeners and for getting information about existing indication
subscriptions.
The WBEM listener is identified through its URL, so it may be a
WBEMListener
object or any external WBEM listener.
This subscription manager supports two types of subscriptions, filters and listener destinations:
Owned subscriptions, filters, and listener destinations - These are indication subscription, indication filter and listener destination CIM instances in a WBEM server whose life cycle is bound to the life cycle of the registration of that WBEM server with the subscription manager.
Such owned CIM instances are deleted automatically when their WBEM server is deregistered from the subscription manager (see
remove_server()
andremove_all_servers()
).Not-owned subscriptions, filters, and listener destinations - These are indication subscription, indication filter and listener destination CIM instances in a WBEM server whose life cycle is independent of the life cycle of the registration of that WBEM server with the subscription manager.
Such not-owned CIM instances are not deleted automatically when their WBEM server is deregistered from the subscription manager. Instead, the user needs to take care of deleting them (if they can and should be deleted). For example, a static indication filter can be used for subscribing to it using this subscription manager, but it cannot be deleted. Also, if some other entity has created such CIM instances in a WBEM server, this client may want to use them but not delete them.
Owned and not-owned subscriptions, filters, and listener destinations can be arbitrarily mixed, with one exception:
- A not-owned subscription cannot be created with an owned filter and/or an
owned listener destination because that would prevent the automatic life
cycle management of the owned filter or listener destination by the
subscription manager. This restriction is enforced by the
WBEMSubscriptionManager
class.
The WBEMSubscriptionManager
object remembers owned
subscriptions, filters, and listener destinations. If for some reason that
object gets deleted (e.g. because the Python program aborts) before all servers
could be removed, the corresponding CIM instances in the WBEM server still
exist, but the knowledge that these instances were owned by that subscription
manager, is lost. Therefore, these instances will be considered not-owned
by any other subscription managers, including a restarted instance of the
subscription manager that went away.
5.2.1. Examples¶
The following example code combines a subscription manager and listener to subscribe for a CIM alert indication on two WBEM servers and register a callback function for indication delivery:
import sys
from socket import getfqdn
from pywbem import WBEMConnection, WBEMListener, WBEMServer,
WBEMSubscriptionManager
def process_indication(indication, host):
'''This function gets called when an indication is received.'''
print("Received CIM indication from {host}: {ind!r}". \
format(host=host, ind=indication))
def main():
certkeyfile = 'listener.pem'
url1 = 'http://server1'
conn1 = WBEMConnection(url1)
server1 = WBEMServer(conn1)
server1.determine_interop_ns()
url2 = 'http://server2'
conn2 = WBEMConnection(url2)
server2 = WBEMServer(conn2)
server2.validate_interop_ns('root/PG_InterOp')
my_listener = WBEMListener(host=getfqdn()
http_port=5988,
https_port=5989,
certfile=certkeyfile,
keyfile=certkeyfile)
my_listener.add_callback(process_indication)
listener.start()
subscription_manager = WBEMSubscriptionManager(
subscription_manager_id='fred')
server1_id = subscription_manager.add_server(server1)
subscription_manager.add_listener_destinations(server1_id,
'http://localhost:5988')
server2_id = subscription_manager.add_server(server2_id)
subscription_manager.add_listener_destinations(server2,
'https://localhost:5989')
# Subscribe for a static filter of a given name
filter1_paths = subscription_manager.get_all_filters(url1)
for fp in filter1_paths:
if fp.keybindings['Name'] == \
"DMTF:Indications:GlobalAlertIndicationFilter":
subscription_manager.add_subscription(url1, fp)
break
# Create a dynamic alert indication filter and subscribe for it
filter2_path = subscription_manager.add_filter(
url2,
query_language="DMTF:CQL"
query="SELECT * FROM CIM_AlertIndication " \
"WHERE OwningEntity = 'DMTF' " \
"AND MessageID LIKE 'SVPC0123|SVPC0124|SVPC0125'")
subscription_manager.add_subscription(server2_id, filter2_path)
Another more practical example is in the script
examples/pegIndicationTest.py
(when you clone the GitHub pywbem/pywbem
project).
-
class
pywbem.
WBEMSubscriptionManager
(subscription_manager_id=None)[source]¶ A class for managing subscriptions for CIM indications in a WBEM server.
Parameters: subscription_manager_id (string) – A subscription manager ID string that is used as a component in the value of the Name properties of filter and listener destination instances to help the user identify these instances in a WBEM server.
The string must consist of printable characters, and not contain the character ‘:’ because that is the separator between components within the value of these Name properties.
There is no requirement that the subscription manager ID be unique.
None indicates that the subscription manager ID should not be included in the value of these Name properties.
For example, the form of the Name property of a filter instance is:
"pywbemfilter:" [{subscription_manager_id} ":"] [{filter_id} ":"] {guid}
-
__repr__
()[source]¶ Return a representation of the
WBEMSubscriptionManager
object with all attributes, that is suitable for debugging.
-
add_server
(server)[source]¶ Register a WBEM server with the subscription manager. This is a prerequisite for adding listener destinations, indication filters and indication subscriptions to the server.
Parameters: server ( WBEMServer
) – The WBEM server.Returns: An ID for the WBEM server, for use by other methods of this class. Return type: string Raises: Exceptions raised by WBEMConnection
.
-
remove_server
(server_id)[source]¶ Remove a registered WBEM server from the subscription manager. This also unregisters listeners from that server and removes all owned indication subscriptions, owned indication filters and owned listener destinations that were created by this subscription manager for that server.
Parameters: server_id (string) – The server ID of the WBEM server, returned by add_server()
.Raises: Exceptions raised by WBEMConnection
.
-
remove_all_servers
()[source]¶ Remove all registered WBEM servers from the subscription manager. This also unregisters listeners from these servers and removes all owned indication subscriptions, owned indication filters, and owned listener destinations that were created by this subscription manager.
This is, in effect, a complete shutdown of the subscription manager.
Raises: Exceptions raised by WBEMConnection
.
-
add_listener_destinations
(server_id, listener_urls, owned=True)[source]¶ Register WBEM listeners to be the target of indications sent by a WBEM server.
This function automatically creates a listener destination instance (of CIM class “CIM_ListenerDestinationCIMXML”) for each specified listener URL in the Interop namespace of the specified WBEM server.
Parameters: - server_id (string) – The server ID of the WBEM server, returned by
add_server()
. - listener_urls (string or list of string) –
The URL or URLs of the WBEM listeners to be registered.
The WBEM listener may be a
WBEMListener
object or any external WBEM listener.Each listener URL string must have the format:
[{scheme}://]{host}:{port}
The following URL schemes are supported:
https
: Causes HTTPS to be used.http
: Causes HTTP to be used. This is the default
The host can be specified in any of the usual formats:
- a short or fully qualified DNS hostname
- a literal (= dotted) IPv4 address
- a literal IPv6 address, formatted as defined in RFC3986
with the extensions for zone identifiers as defined in
RFC6874, supporting
-
(minus) for the delimiter before the zone ID string, as an additional choice to%25
.
Note that the port is required in listener URLs.
See
WBEMConnection
for examples of valid URLs, with the caveat that the port in server URLs is optional. - owned (
bool
) –Defines whether or not the listener destination instances that are created in the WBEM server are owned by the subscription manager.
If True, these listener destination instances are owned and will have a life cycle that is bound to the registration of the WBEM server within this subscription manager. The user does not need to take care of deleting these instances in the WBEM server. Instead, if the WBEM server is deregistered from this subscription manager (see
remove_server()
andremove_all_servers()
), these listener destination instances will be automatically deleted in the WBEM server.If False, these listener destination instances are not-owned and will have a life cycle that is independent of the registration of the WBEM server within this subscription manager. The user is responsible for deleting these listener destination instances explicitly (for example by using
remove_destinations()
).
Returns: The instance paths of the created listener destination instances for the defined listener URLs.
Return type: Raises: Exceptions raised by
WBEMConnection
.- server_id (string) – The server ID of the WBEM server, returned by
-
get_all_destinations
(server_id)[source]¶ Return all listener destinations in a WBEM server.
This function contacts the WBEM server and retrieves the listener destinations by enumerating the instances of CIM class “CIM_ListenerDestinationCIMXML” in the Interop namespace of the WBEM server.
Parameters: server_id (string) – The server ID of the WBEM server, returned by add_server()
.Returns: The instance paths of the listener destination instances. Return type: list
ofCIMInstanceName
Raises: Exceptions raised by WBEMConnection
.
-
remove_destinations
(server_id, destination_paths)[source]¶ Remove listener destinations from a WBEM server, by deleting the listener destination instances in the server.
The listener destinations may be owned or not-owned.
Parameters: - server_id (string) – The server ID of the WBEM server, returned by
add_server()
. - destination_paths (
CIMInstanceName
or list ofCIMInstanceName
) – Instance path(s) of the listener destination instance(s) in the WBEM server.
Raises: Exceptions raised by
WBEMConnection
.- server_id (string) – The server ID of the WBEM server, returned by
-
add_filter
(server_id, source_namespace, query, query_language='WQL', owned=True, filter_id=None)[source]¶ Add a dynamic indication filter to a WBEM server, by creating an indication filter instance (of CIM class “CIM_IndicationFilter”) in the Interop namespace of the server.
Parameters: - server_id (string) – The server ID of the WBEM server, returned by
add_server()
. - source_namespace (string) – Source namespace of the indication filter.
- query (string) – Filter query in the specified query language.
- query_language (string) –
Query language for the specified filter query.
Examples: ‘WQL’, ‘DMTF:CQL’.
- owned (
bool
) –Defines whether or not the filter instances that are created in the WBEM server are owned by the subscription manager.
If True, these filter instances are owned and will have a life cycle that is bound to the registration of the WBEM server within this subscription manager. The user does not need to take care of deleting these instances in the WBEM server. Instead, if the WBEM server is deregistered from this subscription manager (see
remove_server()
andremove_all_servers()
), these filter instances will be automatically deleted in the WBEM server. The user may also delete these filter instances explicitly (for example by usingremove_filter()
).If False, these filter instances are not-owned and will have a life cycle that is independent of the registration of the WBEM server within this subscription manager. The user is responsible for deleting these filter instances explicitly (for example by using
remove_filter()
). - filter_id (string) –
A filter ID string that is used as a component in the value of the Name properties of filter instances to help the user identify these instances in a WBEM server.
There is no requirement that the filter ID be unique. This can be used to identify groups of filters by using the same value for multiple filters.
The string must consist of printable characters, and not contain the character ‘:’ because that is the separator between components within the value of these Name properties.
None indicates that the filter ID should not be included in the value of these Name properties.
The form of the Name property of the created filter instance is:
"pywbemfilter:" [{subscription_manager_id} ":"] [{filter_id} ":"] {guid}
Returns: The instance path of the indication filter instance.
Return type: Raises: Exceptions raised by
WBEMConnection
.- server_id (string) – The server ID of the WBEM server, returned by
-
get_owned_filters
(server_id)[source]¶ Return the owned indication filters in a WBEM server that have been created by this subscription manager.
This function accesses only the local list of owned filters; it does not contact the WBEM server.
Parameters: server_id (string) – The server ID of the WBEM server, returned by add_server()
.Returns: The instance paths of the indication filter instances. Return type: list
ofCIMInstanceName
Raises: Exceptions raised by WBEMConnection
.
-
get_all_filters
(server_id)[source]¶ Return all indication filters in a WBEM server.
This function contacts the WBEM server and retrieves the indication filters by enumerating the instances of CIM class “CIM_IndicationFilter” in the Interop namespace of the WBEM server.
Parameters: server_id (string) – The server ID of the WBEM server, returned by add_server()
.Returns: The instance paths of the indication filter instances. Return type: list
ofCIMInstanceName
Raises: Exceptions raised by WBEMConnection
.
-
remove_filter
(server_id, filter_path)[source]¶ Remove an indication filter from a WBEM server, by deleting the indication filter instance in the WBEM server.
The indication filter must be a dynamic filter but may be owned or not-owned.
Parameters: - server_id (string) – The server ID of the WBEM server, returned by
add_server()
. - filter_path (
CIMInstanceName
) – Instance path of the indication filter instance in the WBEM server.
Raises: Exceptions raised by
WBEMConnection
.- server_id (string) – The server ID of the WBEM server, returned by
-
add_subscriptions
(server_id, filter_path, destination_paths=None, owned=True)[source]¶ Add subscriptions to a WBEM server for a particular set of indications defined by an indication filter and for a particular set of WBEM listeners defined by the instance paths of their listener destination instances in that WBEM server, by creating indication subscription instances (of CIM class “CIM_IndicationSubscription”) in the Interop namespace of that server.
The indication filter can be an (owned or not-owned) dynamic filter created via
add_filter()
, or a dynamic or static filter that already exists in the WBEM server. Existing filters in the WBEM server can be retrieved viaget_all_filters()
.Upon successful return of this method, the added subscriptions are active, so that the specified WBEM listeners may immediately receive indications.
Parameters: - server_id (string) – The server ID of the WBEM server, returned by
add_server()
. - filter_path (
CIMInstanceName
) –Instance path of the indication filter instance in the WBEM server that specifies the indications to be sent.
When creating not-owned subscriptions, this filter also must be not-owned.
- destination_paths (
CIMInstanceName
or list ofCIMInstanceName
) –If not None, subscriptions will be created for the listener destinations whose instance paths are specified in this argument.
If None, subscriptions will be created for all owned listener destinations registered to this subscription manager.
When creating not-owned subscriptions, all involved listener destinations must be not-owned, too.
- owned (
bool
) –Defines whether or not the subscription instances that are created in the WBEM server are owned by the subscription manager.
If True, these subscription instances are owned and will have a life cycle that is bound to the registration of the WBEM server within this subscription manager. The user does not need to take care of deleting these subscription instances in the WBEM server. Instead, if the WBEM server is deregistered from this subscription manager (see
remove_server()
andremove_all_servers()
), these subscription instances will be automatically deleted in the WBEM server. The user may also delete these subscription instances explicitly (for example by usingremove_subscriptions()
).If False, these subscription instances are not-owned and will have a life cycle that is independent of the registration of the WBEM server within this subscription manager. The user is responsible for deleting these subscription instances explicitly (for example by using
remove_subscriptions()
).
Returns: The instance paths of the indication subscription instances created in the WBEM server.
Return type: Raises: Exceptions raised by
WBEMConnection
.- server_id (string) – The server ID of the WBEM server, returned by
-
get_owned_subscriptions
(server_id)[source]¶ Return the owned indication subscriptions for a WBEM server that have been created by this subscription manager.
This function accesses only the local list of owned subscriptions; it does not contact the WBEM server.
Parameters: server_id (string) – The server ID of the WBEM server, returned by add_server()
.Returns: The instance paths of the indication subscription instances. Return type: list
ofCIMInstanceName
Raises: Exceptions raised by WBEMConnection
.
-
get_all_subscriptions
(server_id)[source]¶ Return all indication subscriptions in a WBEM server.
This function contacts the WBEM server and retrieves the indication subscriptions by enumerating the instances of CIM class “CIM_IndicationSubscription” in the Interop namespace of the WBEM server.
Parameters: server_id (string) – The server ID of the WBEM server, returned by add_server()
.Returns: The instance paths of the indication subscription instances. Return type: list
ofCIMInstanceName
Raises: Exceptions raised by WBEMConnection
.
-
remove_subscriptions
(server_id, sub_paths)[source]¶ Remove indication subscription(s) from a WBEM server, by deleting the indication subscription instances in the server.
The indication subscriptions may be owned or not-owned.
Parameters: - server_id (string) – The server ID of the WBEM server, returned by
add_server()
. - sub_paths (
CIMInstanceName
or list ofCIMInstanceName
) – Instance path(s) of the indication subscription instance(s) in the WBEM server.
Raises: Exceptions raised by
WBEMConnection
.- server_id (string) – The server ID of the WBEM server, returned by
-