1. Introduction

1.1. Functionality

Pywbem supports the following functionality:

  • WBEM client library API

    This API supports issuing WBEM operations to a WBEM server, using the CIM operations over HTTP (CIM-XML) protocol defined in the DMTF standards DSP0200 and DSP0201.

  • WBEM server API

    This API encapsulates certain functionality of a WBEM server for use by a WBEM client application, such as determining the Interop namespace of the server, or the management profiles advertised by the server.

  • WBEM indication API

    This API supports starting and stopping a WBEM listener that waits for indications (i.e. events) emitted by a WBEM server using the CIM-XML protocol. The API also supports managing subscriptions for such indications.

  • MOF compiler API

    This API provides for invoking the MOF compiler and for plugging in your own CIM repository into the MOF compiler.

  • WBEM utility commands

    Pywbem includes a few utility commands:

    • mof_compiler

      A MOF compiler that takes MOF files as input and updates the CIM repository of a WBEM server with the result. See DSP0004 for a definition of MOF.

    • wbemcli

      A WBEM client in the form of a shell that provides an interactive Python environment for issuing WBEM operations to a WBEM server.

1.2. Installation

Pywbem is a pure Python package and therefore does not have a dependency on operating system packages in addition to Python itself. However, some of the Python packages used by pywbem have dependencies on additional operating system packages for their installation. Also, on some platforms, manual post-processing steps are needed, such as setting up environment variables.

This section describes the complete installation of pywbem with all steps including prerequisite operating system packages and manual post-processing steps, for users of pywbem. As a user of pywbem, you can import the pywbem Python package into your programs, and/or you can run the WBEM utility commands that come with pywbem.

If you want to contribute to the pywbem project, you need to set up a development and test environment for pywbem. That has a larger set of OS-level prerequisites and its setup is described in chapter Development.

A note on the pywbem_os_setup.sh script that is used for installation on some platforms: That script installs the Python distro package into the active Python environment. If your active Python environment is a virtual Python environment, that package will obviously be installed into that virtual environment. If your active Python environment is the system Python environment, that package will be installed into the system Python, but as a local package for the current user. So it is not visible in the system Python of other users, but still visible in the system Python of the current user. This is done in order not to pollute the system Python installation with additional Python packages that are not known at the OS-level package manager (e.g. yum on RedHat) and thus may be considered a maintenance problem.

1.2.1. Supported environments

Pywbem is supported in these environments:

  • Operating Systems: Linux, Windows (native, and with UNIX-like environments), OS-X
  • Python: 2.6, 2.7, 3.4, 3.5, 3.6 and higher
  • WBEM servers: Any WBEM server that conforms to the DMTF specifications listed in Standards conformance. WBEM servers supporting older versions of these standards are also supported, but may have limitations. See WBEM servers for more details.

Limitations:

  • On Windows (native), pywbem is not supported on Python 2.6, because the M2CryptoWin32/64 packages do not support Python 2.6.

1.2.2. Installing to Linux

  • Download the pywbem_os_setup.sh script from one of these sources:

    That script installs OS-level prerequisite packages needed by pywbem.

  • Execute the pywbem_os_setup.sh script:

    $ ./pywbem_os_setup.sh
    

    The script uses sudo under the covers to invoke the OS-level package manager for your Linux distribution (e.g. yum on the RedHat family), so the current userid needs to have sudo permission.

    On older Linux versions, the Swig utility may not be available in the required version. In that case, the pywbem_os_setup.sh script will report that as an issue and one option on how to proceed is to build Swig yourself as described in Building Swig, and then to repeat execution of the pywbem_os_setup.sh script.

    In case the script reports that your Linux distribution is not supported by the script, you can still try to find out what the corresponding OS-level packages are on your Linux distribution and install them manually. The script will list the names and versions of the OS-level packages for RedHat in that case, and you would need to find out what the corresponding packages are on your desired Linux distribution. If you were able to find these packages, please open an issue so we can add support for that Linux distribution to the script.

  • Only on Python 2.6 on Linux Debian family systems with multi-architecture support (e.g. Ubuntu 16.04 and higher):

    Perform the following workaround to make the multi-architecture header files of OpenSSL available in a compatible way (the example is for x86_64 systems):

    $ sudo ln -s /usr/include/x86_64-linux-gnu/openssl/opensslconf.h /usr/include/openssl/opensslconf.h
    

    Background: One of the packages needed by pywbem on Python 2 is M2Crypto. During its own installation as a Python package, M2Crypto needs the OpenSSL header files. On Linux Debian family systems with multi-architecture support, the structure of OpenSSL header files changed incompatibly (compared to earlier versions of these distributions). The installation of M2Crypto tries to accomodate that incompatibility by detecting multi-architecture support, but on Python 2.6 the interface for that was not yet supported. As a result, the OpenSSL header files are not found. The workaround established in this step makes the OpenSSL header files available in a compatible way, so that the M2Crypto installation finds them.

  • Install pywbem (and its prerequisite Python packages) into the active Python environment:

    $ pip install pywbem
    

1.2.3. Installing to OS-X

  • Download the pywbem_os_setup.sh script from one of these sources:

    That script installs OS-level prerequisite packages needed by pywbem.

  • Execute the pywbem_os_setup.sh script:

    $ ./pywbem_os_setup.sh
    

    The script uses sudo under the covers to invoke brew (Homebrew project) to install OS-level packages, so the current userid needs to have sudo permission.

  • Only on Python 2 on newer OS-X releases:

    The pywbem_os_setup.sh script installs the openssl package needed by the M2Crypto Python package. On newer OS-X releases, you may see a notice that the openssl package is “not linked” because the TLS implementation provided with OS-X is available. In that case, you need to set up the following environment variables for use by the pywbem package installation described in the next step:

    $ openssl_dir=$(brew --prefix openssl)
    $ export LDFLAGS="-L$openssl_dir/lib $LDFLAGS"
    $ export CFLAGS="-I$openssl_dir/include $CFLAGS"
    $ export SWIG_FEATURES="-I$openssl_dir/include $SWIG_FEATURES"
    
  • Install pywbem (and its prerequisite Python packages) into the active Python environment:

    $ pip install pywbem
    

1.2.4. Installing to native Windows

This section describes the installation of pywbem into a native Windows environment (i.e. without using a UNIX-like environment; for that, see Installing to a UNIX-like environment under Windows):

  • Determine the bit size of the active Python environment, for example as follows:

    > python -c "import ctypes; print(ctypes.sizeof(ctypes.c_void_p)*8)"
    64
    
  • Install the Windows build of M2Crypto into the active Python environment:

    For a 32-bit Python environment:

    > pip install M2CryptoWin32
    

    For a 64-bit Python environment:

    > pip install M2CryptoWin64
    

    Note that these Python packages are binary builds and therefore do not invoke Swig at their installation time. Therefore, there are no prerequisite OS-level packages to install.

  • Install pywbem (and its other prerequisite Python packages) into the active Python environment:

    > pip install pywbem
    

1.2.5. Installing to a UNIX-like environment under Windows

This section describes the installation of pywbem into a UNIX-like environment under Windows (such as CygWin, MinGW, Babun, or Gow).

Note that Unix-like environments on Windows bring their own Python, so in such an environment, you install into that Python, and not into the Python of Windows.

  • Install pywbem (and its other prerequisite Python packages) into the active Python environment:

    > pip install pywbem
    

    If the Swig compilation during installation of M2Crypto fails, there may be components of the UNIX-like environment missing. When using CygWin, these may be installed using the CygWin setup program, and the packages are listed in Prerequisite operating system packages for install. For other UNIX-like environments, there should be similar packages (please tell us by opening an issue).

1.2.6. Installing into a different Python environment

The examples in the previous sections install pywbem and its prerequisite Python packages using the Pip utility. By default, Pip installs these packages into the currently active Python environment. That can be the system Python, or a virtual Python. The commands shown above did not detail this, but this section does.

If you just want to use the scripts that come with pywbem, and want them to be always available without having to think about activating virtual Python environments, then installation of pywbem into the system Python environment is probably the right choice for you. If your intention is to write code against the pywbem APIs, installation into a virtual Python environment is recommended.

An additional dimension is Python 2 vs. Python 3:

  • On systems where Python 2 is the default, the python and pip commands operate on Python 2. There may be python3 and pip3 commands that operate on Python 3.
  • On some newer systems (e.g. Ubuntu 17.04), Python 3 is the default. In that case, the python and pip commands operate on Python 3. There may be python2 and pip2 commands that operate on Python 2.

For simplicity, the following examples show only the default commands.

  • To install pywbem into the currently active virtual Python environment (e.g. myenv), issue:

    (myenv)$ pip install pywbem
    
  • To install pywbem for only the current user into the currently active system Python environment, issue:

    $ pip install --user pywbem
    

    This installs the Python packages in a directory under the home directory of the current user and therefore does not require sudo permissions nor does it modify the system Python environment seen by other users.

  • To install pywbem for all users into the currently active system Python environment, issue:

    $ sudo pip install pywbem
    

    This installs the Python packages into a directory of the system Python installation and therefore requires sudo permissions.

    Be aware that this may replace the content of existing packages when a package version is updated. Such updated packages as well as any newly installed packages are not known by your operating system installer, so the knowledge of your operating system installer is now out of sync with the actual set of packages in the system Python.

    Therefore, this approach is not recommended and you should apply this approach only after you have thought about how you would maintain these Python packages in the future.

1.2.7. Installing a different version of pywbem

The examples in the previous sections install the latest version of pywbem that is released on PyPI. This section describes how different versions of pywbem can be installed.

  • To install the latest version of pywbem that is released on PyPI, issue:

    $ pip install pywbem
    
  • To install an older released version of pywbem, Pip supports specifying a version requirement. The following example installs pywbem version 0.10.0 from PyPI:

    $ pip install pywbem==0.10.0
    
  • If you need to get a certain new functionality or a new fix of pywbem that is not yet part of a version released to PyPI, Pip supports installation from a Git repository. The following example installs pywbem from the current code level in the master branch of the pywbem Git repository:

    $ pip install git+https://github.com/pywbem/pywbem.git@master#egg=pywbem
    

1.2.8. Verifying the installation

You can verify that pywbem is installed correctly by importing the package into Python (using the Python environment you installed pywbem to):

$ python -c "import pywbem; print('ok')"
ok

In case of trouble with the installation, see the Troubleshooting section.

1.2.9. Prerequisite operating system packages for install

The following table lists the prerequisite operating system packages along with their version requirements for installing and running pywbem, for the supported operating systems and Linux distributions. This list is for reference only, because the installation steps in the previous sections already take care of getting these packages installed.

The prerequisite operating system packages for developing pywbem are not listed in this table; you can find them in section Prerequisite operating system packages for development.

Op.system / Distribution Package name Version requirements Notes
Linux RedHat family (RHEL, CentOS, Fedora) openssl-devel >=1.0.1 py2
python-devel for your Python 2.x py2
gcc-c++ >=4.4 py2
swig >=2.0 py2
Linux Debian family (Ubuntu, Debian, LinuxMint) libssl-dev >=1.0.1 py2
python-dev for your Python 2.x py2
g++ >=4.4 py2
swig >=2.0 py2
Linux SUSE family (SLES, openSUSE) openssl-devel >=1.0.1 py2
python-devel for your Python 2.x py2
gcc-c++ >=4.4 py2
swig >=2.0 py2
OS-X openssl >=1.0.1 py2
gcc >=4.4 py2
swig >=2.0 py2
Windows (native) None    
Windows (CygWin) openssl-devel   py2
python2-devel   py2
gcc-g++   py2
swig   py2

Notes:

  • py2: Only needed with Python 2 (not needed with Python 3).

1.2.10. Building Swig

The installation of M2Crypto needs the Swig utility (e.g. swig package on RedHat). On some Linux distributions, the Swig utility is not available in the required version. In such cases, it can be built from its sources, as follows:

  1. Install the PCRE development packages:

    • pcre-devel package on Linux RedHat and SUSE families
    • libpcre3 and libpcre3-dev packages on Linux Debian family
  2. Download the source archive of Swig version 2.0 or higher, and unpack it. For example, using Swig version 2.0.12:

    $ wget -q -O swig-2.0.12.tar.gz http://sourceforge.net/projects/swig/files/swig/swig-2.0.12/swig-2.0.12.tar.gz/download
    $ tar -xf swig-2.0.12.tar.gz
    
  3. Configure and build Swig:

    $ cd swig-2.0.12
    $ ./configure --prefix=/usr
    $ make swig
    
  4. Install Swig (for all users of the system):

    $ sudo make install
    
  5. Verify the installation and the version of Swig:

    $ swig -version
    SWIG Version 2.0.12
    

1.3. Package version

The version of the pywbem package can be accessed by programs using the pywbem.__version__ variable:

pywbem._version.__version__ = '0.12.1.dev23'

The full version of this package including any development levels, as a string.

Possible formats for this version string are:

  • “M.N.P.devNNN”: Development level NNN of a not yet released assumed M.N.P version
  • “M.N.P”: A released M.N.P version

Note: For tooling reasons, the variable is shown as pywbem._version.__version__, but it should be used as pywbem.__version__.

1.4. Standards conformance

The pywbem client and pywbem indication listener conform to the following CIM and WBEM standards, in the version specified when following the links to the standards:

  • The implementation of the CIM-XML protocol in pywbem (client and listener) conforms to DSP0200 and DSP0201.

    Limitations:

    • The mock support of pywbem (see Mock support) does not support the ModifyClass operation. Note that in its implementation of the CIM-XML protocol, pywbem does support the ModifyClass operation.
    • The EnumerationCount operation is not supported by pywbem. That operation is optional for WBEM servers to support, and is hard to implement reasonably.
    • Multi-requests are not supported by pywbem. This is not a functional limitation though, because the use of multi-requests is entirely determined by the client: If a client does not use multi-requests, the server does not use multi-responses.

    Notes:

    • The CIM-XML representation as defined in DSP0201 supports CIM methods that have a void return type. However, the CIM architecture defined in DSP0004 does not support that, and neither does pywbem.
    • The CIM-XML representation as defined in DSP0201 supports references to CIM classes. However, the CIM architecture defined in DSP0004 does not support that, and neither does pywbem.
  • The CIM-XML representation of CIM objects as produced by their tocimxml() and tocimxmlstr() methods conforms to the representations for these objects as defined in DSP0201.

    Limitations:

    • The xml:lang attribute supported by DSP0201 on some CIM-XML elements that can have string values is tolerated in the CIM-XML received by pywbem, but is ignored and is not represented on the corresponding CIM objects.
  • The capabilities of CIM objects conform to the CIM architecture as defined in DSP0004.

  • The MOF as produced by the tomof() methods on CIM objects and as parsed by the MOF compiler conforms to the MOF syntax as defined in DSP0004.

    Limitations:

    • The pywbem MOF compiler has the restriction that CIM instances specified in MOF that have an alias must have key properties that are either initialized in the instance, or have non-NULL default values (issue #1079).
    • The pywbem MOF compiler has the restriction that an alias must be defined before it is used. In the MOF syntax defined in DSP0004, no such restriction exists (issue #1078).
    • The pywbem MOF compiler does not roll back changes to qualifier declarations when it aborts (issue #990).
  • The WBEM URIs produced by the to_wbem_uri() methods of CIMInstanceName and CIMClassName conform to the WBEM URI syntax as defined in DSP0207.

    Note that the __str__() methods of these two classes produce strings that are similar but not conformant to DSP0207, for historical reasons.

  • The mechanisms for discovering the Interop namespace of a WBEM server and the management profiles advertised by a WBEM server and their central instances in the WBEM server API conform to DSP1033.

  • The mechanisms for subscribing for CIM indications in the WBEM indication API conform to DSP1054.

1.5. Deprecation and compatibility policy

Since version 0.7.0, pywbem attempts to be as backwards compatible as possible.

Compatibility of pywbem is always seen from the perspective of the user of the pywbem APIs or pywbem utility commands. Thus, a backwards compatible new version of pywbem means that a user can safely upgrade to that new version without encountering compatibility issues for their code using the pywbem APIs or for their scripts using the pywbem utility commands.

Having said that, there is always the possibility that even a bug fix changes some behavior a user was dependent upon. Over time, the pywbem project has put automated regression testing in place that tests the behavior at the APIs, but such compatibility issues cannot be entirely excluded.

Pywbem uses the rules of Semantic Versioning 2.0.0 for compatibility between versions, and for deprecations. The public interface that is subject to the semantic versioning rules and specificically to its compatibility rules are the various pywbem APIs described in this documentation, and the command line interface of the pywbem utility commands.

Occasionally functionality needs to be retired, because it is flawed and a better but incompatible replacement has emerged. In pywbem, such changes are done by deprecating existing functionality, without removing it immediately. The deprecated functionality is still supported at least throughout new minor or update releases within the same major release. Eventually, a new major release may break compatibility by removing deprecated functionality.

Any changes at the pywbem APIs or utility commands that do introduce incompatibilities as defined above, are described in the Change log.

Deprecation of functionality at the pywbem APIs or utility commands is communicated to the users in multiple ways:

  • It is described in the documentation of the API or utility command
  • It is mentioned in the change log.
  • It is raised at runtime by issuing Python warnings of type DeprecationWarning (see the Python warnings module).

Since Python 2.7, DeprecationWarning messages are suppressed by default. They can be shown for example in any of these ways:

  • By specifying the Python command line option: -W default
  • By invoking Python with the environment variable: PYTHONWARNINGS=default

It is recommended that users of the pywbem package run their test code with DeprecationWarning messages being shown, so they become aware of any use of deprecated functionality.

Here is a summary of the deprecation and compatibility policy used by pywbem, by release type:

  • New update release (M.N.U -> M.N.U+1): No new deprecations; no new functionality; backwards compatible.
  • New minor release (M.N.U -> M.N+1.0): New deprecations may be added; functionality may be extended; backwards compatible.
  • New major release (M.N.U -> M+1.0.0): Deprecated functionality may get removed; functionality may be extended or changed; backwards compatibility may be broken.

1.6. Python namespaces

The external APIs of pywbem are defined by the symbols in the pywbem namespace. That is the only Python namespace that needs to be imported by users.

With pywbem versions prior to v0.8, it was common for users to import the sub-modules of pywbem (e.g. pywbem.cim_obj). The sub-modules that existed prior to v0.8 are still available for compatibility reasons. Starting with v0.8, the pywbem namespace was cleaned up, and not all public symbols available in the sub-module namespaces are available in the pywbem namespace anymore. The symbols in the sub-module namespaces are still available for compatibility, including those that are no longer available in the pywbem namespace. However, any use of symbols from the sub-module namespaces is deprecated starting with v0.8, and you should assume that a future version of pywbem will remove them. If you miss any symbol you were used to use, please open an issue.

New sub-modules added since pywbem v0.8 have a leading underscore in their name in order to document that they are considered an implementation detail and that they should not be imported by users.

With pywbem versions prior to v0.11, the MOF compiler API was only available in the pywbem.mof_compiler namespace. Starting with pywbem version v0.11, it is also available in the pywbem namespace and should be used from there.

This documentation describes only the external APIs of pywbem, and omits any internal symbols and any sub-modules.

1.7. Configuration variables

Pywbem supports a very limited number of configuration variables that influence certain specific behavior.

These configuration variables are read by pywbem only after its modules have been loaded, so they can be modified by the user directly after importing pywbem. For example:

import pywbem
pywbem.ENFORCE_INTEGER_RANGE = False

Note that the pywbem source file defining these variables should not be changed by the user. Instead, the technique shown in the example above should be used to modify the configuration variables.

Note: Due to limitations of the documentation tooling, the following configuration variables are shown in the pywbem.config namespace. However, they should be used from the pywbem namespace.

pywbem.config.ENFORCE_INTEGER_RANGE = True

Enforce the allowable value range for CIM integer types (e.g. Uint8). For details, see the CIMInt base class.

  • True (default): Pywbem enforces the allowable value range; Assigning values out of range causes ValueError to be raised.
  • False: Pywbem does not enforce the allowable value range; Assigning values out of range works in pywbem. Note that a WBEM server may or may not reject such out-of-range values.

New in pywbem 0.9.

pywbem.config.DEFAULT_ITER_MAXOBJECTCOUNT = 1000

Default setting for the MaxObjectCount attribute for all of the WBEMConnection:Iter… operations. If this attribute is not specified on a request such as IterEnumerateInstances(), this value will be used as the value for MaxObjectCount. Note that this does not necessarily optimize the performance of these operations.

New in pywbem 0.10 as experimental and finalized in 0.12.

pywbem.config.SEND_VALUE_NULL = True

Backwards compatibility option controlling the use of VALUE.NULL for representing NULL entries in array values in CIM-XML requests sent to WBEM servers.

DSP0201 requires the use of VALUE.NULL for representing NULL entries in array values since its version 2.2 (released 01/2007). Pywbem added support for using VALUE.NULL in CIM-XML requests in its version 0.12. In case a WBEM server has not implemented support for VALUE.NULL, this config option can be used to disable the use of VALUE.NULL as a means for backwards compatibility with such WBEM servers.

Note that the config option only influences the behavior of pywbem for using VALUE.NULL in CIM-XML requests sent to a WBEM server. Regardless of the config option, pywbem will always support VALUE.NULL in CIM-XML responses the pywbem client receives from a WBEM server, and in CIM-XML requests the pywbem listener receives from a WBEM server.

  • True (default): Pywbem uses VALUE.NULL in CIM-XML requests for representing NULL entries in array values.
  • False: Pywbem uses VALUE with an empty value in CIM-XML requests for representing NULL entries in array values.

New in pywbem 0.12.

1.8. WBEM servers

1.8.1. Server-specific features

Pywbem supports the following features of some specific WBEM servers that are additions to the DMTF standards:

  1. OpenPegasus
    • Pywbem supports the Interop namespace root/PG_InterOp that is specific to OpenPegasus. OpenPegasus also supports the standard Interop namespaces (interop, root/interop) but for backwards compatibility with earlier versions of OpenPegasus, pywbem supports this old Interop namespace, for example in its Interop namespace determination whose result is exposed in the pywbem.WBEMServer.interop_ns property.
    • Pywbem supports the upper-case variant EMBEDDEDOBJECT of the respective CIM-XML attribute that is specific to some releases of OpenPegasus, in addition to the mixed-case variant EmbeddedObject that is defined in the DSP0201 standard and that is also supported by OpenPegasus. Older releases of OpenPegasus supported only the upper-case variant.
    • Pywbem supports a connection to an OpenPegasus server using Unix Domain Sockets through its PegasusUDSConnection subclass of WBEMConnection.
  2. SFCB (Small Footprint CIM Broker)
    • Pywbem supports a connection to an SFCB server using Unix Domain Sockets through its SFCBUDSConnection subclass of WBEMConnection.
  3. OpenWBEM
    • Pywbem supports the OWlocal authentication extension of OpenWBEM, which is a password-less local authorization.
    • Pywbem supports a connection to an OpenWBEM server using Unix Domain Sockets through its OpenWBEMUDSConnection subclass of WBEMConnection.

1.8.2. WBEM server testing

Today the pywbem project tests primarily against current versions of the OpenPegasus WBEM server because that server is available to the project.

These tests are captured in the test script run_cimoperations.py. Note that generally those tests that are server-specific only run against the defined server so that there are a number of tests that run only against the OpenPegasus server. This includes some tests that use specific providers in the OpenPegasus server to set up tests such as indication tests.