1. Introduction¶
1.1. Functionality¶
Pywbem supports the following functionality:
-
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.
-
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.
-
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.
-
This API provides for invoking the MOF compiler and for plugging in your own CIM repository into the MOF compiler.
-
Pywbem includes a few utility commands:
-
A MOF compiler that takes MOF files as input and creates, updates or removes CIM instances, classes or qualifier types in a CIM repository.
See DSP0004 for a description of MOF (Managed Object Format).
By default, the CIM repository used by the MOF compiler is in a WBEM server. The MOF compiler API provides for plugging in your own CIM repository the compiler can work against.
-
A WBEM command line interface that provides an interactive Python environment for issuing WBEM operations to a WBEM server.
-
1.2. Installation¶
Pywbem is a pure Python package that can be installed from PyPi or from its Git repository by the usual means for installing Python packages.
Some of the Python packages used by pywbem have dependencies on operating system packages. These operating system packages must be installed before the pywbem Python package can be installed. For details, see Prerequisite operating system packages.
Pywbem also has dependencies on other Python packages. These Python packages will be automatically installed when installing pywbem using any of the approaches shown below:
Install the latest released version of pywbem (assuming the OS-level prerequisites are already established):
$ pip install pywbem
Install the latest development version of pywbem (assuming the OS-level prerequisites are already established):
$ pip install git+https://github.com/pywbem/pywbem.git@master
Special note for installing on Windows:
The commands shown above do not work in version 0.11 of pywbem because Pip does not invoke pywbem’s setup.py and instead goes by the package metadata. Therefore, installation on Windows (both for native Windows and in UNIX-like environments on Windows such as CygWin) needs to be done as follows:
Clone the Git repository of pywbem and check out the stable branch for the desired version (e.g. branch stable_0.11 for the latest fix version 0.11.x):
> git clone https://github.com/pywbem/pywbem.git > cd pywbem > git checkout stable_0.11
Install the Python prerequsite packages for starting the installation of pywbem, making sure they are at the minimum required version:
> pip install "setuptools>=0.9.8" > pip install "wheel>=0.24.0" > pip install "pip>=8.1"
Install the checked-out version of pywbem using its setup.py:
> python setup.py install
These examples install pywbem and its prerequisite Python packages into the currently active Python environment. By default, the system Python environment is active. This is probably the right choice if you just want to use the scripts that come with pywbem. In that case, you need to use sudo with the commands shown above, and your Linux userid needs to be authorized accordingly. If your intention is to write code against the pywbem APIs, installation into a virtual Python environment is recommended).
The command syntax above is shown for Linux, but works in similar ways on Windows and OS-X.
In case of trouble with the installation, see the Troubleshooting section.
You can verify that pywbem, its dependent Python packages and its dependent OS-level packages are installed correctly by importing the package into Python (using the Python environment you installed pywbem to):
$ python -c "import pywbem; print('ok')"
ok
1.3. Prerequisite operating system packages¶
Some of the Python packages used by pywbem have dependencies on operating system packages. These operating system packages must be installed before the pywbem Python package can be installed. This section describes how that can be done, and documents these packages.
For pywbem 0.11 and higher: Use
pywbem_os_setup.sh
In this approach, a standalone shell script that installs the OS-level prerequisites is downloaded and executed.
The shell script needs the Python
distro
package installed in the current Python environment. If your current Python environment is a virtual Python environment, the shell script will install thedistro
package automatically.If your current Python environment is the system Python, the shell script does not automatically install that Python package, in order not to modify the system Python, and leaves that to you (including the decision whether to switch to a virtual Python environment and then to simply re-run the shell script).
Download the
pywbem_os_setup.sh
shell script for the pywbem version you want to install, and execute that script:$ ./pywbem_os_setup.sh
The script uses
sudo
under the covers, so your userid needs to have sudo permission.
For pywbem 0.8 to 0.10: Use
setup.py install_os
In this approach, the pywbem source archive is downloaded and its
setup.py
script is executed with a pywbem-specific commandinstall_os
.This approach still should work for pywbem versions higher than 0.10, but should not be used anymore.
The examples are shown for pywbem version 0.8.1.
Download the pywbem source archive from Pypi using Pip:
$ pip download --no-deps --no-binary :all: pywbem==0.8.1
The ability to download packages was introduced in Pip 8.0. When using an older Pip version, you can download the pywbem source archive from its Git repository:
$ curl -o pywbem-0.8.1.tar.gz -L https://github.com/pywbem/pywbem/blob/master/dist/pywbem-0.8/pywbem-0.8.1.tar.gz
Of course, you can also download it manually from Pypi. Note that only the source archive (
*.tar.gz
) has the capability we use here; the binary archive (*.whl
) does not have that capability.Extract the pywbem source archive and run the
install_os
command ofsetup.py
:$ tar -xzf pywbem-0.8.1.tar.gz $ cd pywbem-0.8.1 $ python setup.py install_os
The
install_os
command usessudo
under the covers, so your userid needs to have sudo permission.The M2Crypto Python package used by pywbem needs Swig to be installed. The
install_os
command attempts to install Swig. If no suitable version of Swig can be installed, the source archive of Swig is downloaded, and its build prerequisites are installed, and Swig is built. This is only necessary on very old operating systems.
For pywbem before 0.8: Install the required packages manually, based upon the table shown below.
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.
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 | None |
Notes:
- py2: Only needed with Python 2 (not needed with Python 3).
On some distributions, the swig
package is not available in the required
version. In such cases, it can be built from its sources, as follows:
Install the
pcre-devel
package (RedHat etc. and SLES etc.) or thelibpcre3
andlibpcre3-dev
packages (Ubuntu etc.).Download the swig source archive and unpack it:
$ 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
Configure and build it:
$ cd swig-2.0.12 $ ./configure --prefix=/usr $ make swig
Install it:
$ sudo make install
Verify its version:
$ swig -version SWIG Version 2.0.12
1.4. Package version¶
The version of the pywbem package can be accessed by programs using the
pywbem.__version__
variable:
-
pywbem._version.
__version__
= '0.11.1'¶ Version of the pywbem package, as a string.
Possible formats for the version string are:
- “M.N.U.dev0”: During development of future M.N.U release (not released to PyPI)
- “M.N.U.rcX”: Release candidate X of future M.N.U release (not released to PyPI)
- “M.N.U”: The final M.N.U release
Note: For tooling reasons, the variable is shown as
pywbem._version.__version__
, but it should be used as
pywbem.__version__
.
1.5. Supported environments¶
Pywbem is supported in these environments:
- Operating Systems: Linux, Windows, OS-X
- Python: 2.6, 2.7, 3.4, 3.5, 3.6
Limitations:
- On Windows, pywbem is not supported on Python 2.6, because M2Crypto in the M2CryptoWin32/64 package does not support Python 2.6.
- On Windows, pywbem has not been tested on 64-bit versions of Python, because the libxslt etc. development packages needed to install lxml that are used do not provide the link libraries in the format needed by lxml. Because lxml is only used for development and test of pywbem, just running pywbem on 64-bit versions of Windows may or may not work.
1.6. Standards conformance¶
Pywbem conforms to the following CIM and WBEM standards, in the version specified when following the links to the standards:
The supported WBEM protocol is CIM-XML; it conforms to DSP0200 and DSP0201.
The CIM-XML representation of CIM objects as produced by their
tocimxml()
andtocimxmlstr()
methods conforms to DSP0201.The MOF as produced by the
tomof()
methods on CIM objects and as parsed by the MOF compiler conforms to DSP0004.Limitations:
- Several issues in the MOF compiler.
The implemented CIM metamodel (e.g. in the CIM objects) conforms to DSP0004.
The WBEM URIs produced by the
pywbem.CIMInstanceName.__str__()
andpywbem.CIMClassName.__str__()
methods conform to DSP0207.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.7. Deprecation policy¶
Since its v0.7.0, Pywbem attempts to be as backwards compatible as possible.
However, in an attempt to clean up some of its history, and in order to prepare for future additions, the Python namespaces visible to users of pywbem need to be cleaned up.
Also, 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. The deprecated functionality is still supported throughout new minor releases. Eventually, a new major release will break compatibility and will remove the deprecated functionality.
In order to prepare users of pywbem for that, deprecation of functionality is
stated in the API documentation, and is made visible 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; fully backwards compatible.
- New minor release (M.N.U -> M.N+1.0): New deprecations may be added; as backwards compatible as possible.
- New major release (M.N.U -> M+1.0.0): Deprecated functionality may get removed; backwards compatibility may be broken.
Compatibility is always seen from the perspective of the user of pywbem, so a backwards compatible new pywbem release means that the user can safely upgrade to that new release without encountering compatibility issues.
1.8. 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.9. 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 theCIMInt
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.
- True (default): Pywbem enforces the allowable value range; Assigning
values out of range causes
-
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 asIterEnumerateInstances()
, this value will be used as the value for MaxObjectCount. Note that this does not necessarily optimize the performance of these operations.
-
pywbem.config.
DEFAULT_MAX_LOG_ENTRY_SIZE
= 1000¶ Maximum log entry size. An integer that sets the maximum size of each log entry if the log_detail_level flag is set.
-
pywbem.config.
DEFAULT_LOG_DESTINATION
= 'none'¶ Set default log destination. ‘none’ means that there will be no logging.
1.10. WBEM servers¶
Pywbem supports communication with any WBEM server that conforms to the DMTF specifications. See section Standards conformance.
1.10.1. Server Specific Features¶
There are some specific non-specification features that are included in pywbem for support of WBEM server specific features including:
1. OpenWBEM server - includes support for an authentication extension (OWLocal password-less local authorization) that is part of the OpenWBEM server.
2. OpenPegasus - includes support for the special interop namespace that may be used in some OpenPegasus implements root/PG_InterOp. Most implementations have moved to supporting the standard namespace (interop, ‘root/interop’) but for backward compatibility, this old interop namespace name was included in the table of namespaces that are searched by the WBEMServer.get_interop_namespace() method).
3. OpenPegasus - Supports a mixed-case attribute name EmbeddedObject in XML responses that was defined in error in some old versions of OpenPegasus in addtion to the correct upper case.
4. Supports a specific Unix Domain Socket call (the name of the domanin socket) for multiple different servers as subclasses of WBEMConnection including:
- OpenPegasus PegasusUDSConnection
- OpenWBEM - OpenWBEMUDSConnection
- SFCB(Small Footprint CIM Broker) - SFCBUDSConnection
1.10.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 testsuite run_cimoperations.py. Note that generally the 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.