5. WBEM indication API

The WBEM indication API supports subscription for and receiving of CIM indications.

This chapter has the following sections:

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.

host

The IP address or host name this listener can be reached at, as a string.

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 the id() 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 is logging.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 using logging.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.

stop()[source]

Stop the WBEM listener threads, if they are running.

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.
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.

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() and remove_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() and remove_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:

list of CIMInstanceName

Raises:

Exceptions raised by WBEMConnection.

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 of CIMInstanceName
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:
Raises:

Exceptions raised by WBEMConnection.

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() and remove_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 using remove_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:

CIMInstanceName

Raises:

Exceptions raised by WBEMConnection.

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 of CIMInstanceName
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 of CIMInstanceName
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.

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 via get_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 of CIMInstanceName) –

    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() and remove_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 using remove_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:

list of CIMInstanceName

Raises:

Exceptions raised by WBEMConnection.

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 of CIMInstanceName
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 of CIMInstanceName
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:
Raises:

Exceptions raised by WBEMConnection.