1. Introduction¶
1.1. What this package provides¶
The zhmcclient package (also known as python-zhmcclient) is a client library written in pure Python that interacts with the Web Services API of the Hardware Management Console (HMC) of IBM Z or LinuxONE machines. The goal of this package is to make the HMC Web Services API easily consumable for Python programmers.
The HMC Web Services API is the access point for any external tools to manage the IBM Z or LinuxONE platform. It supports management of the lifecycle and configuration of various platform resources, such as partitions, CPU, memory, virtual switches, I/O adapters, and more.
The zhmcclient package encapsulates both protocols supported by the HMC Web Services API:
- REST over HTTPS for request/response-style operations driven by the client. Most of these operations complete synchronously, but some long-running tasks complete asynchronously.
- JMS (Java Messaging Services) for notifications from the HMC to the client. This is used for notification about changes in the system, or about completion of asynchronous tasks started using REST.
1.1.1. zhmc CLI¶
Before version 0.18.0 of the zhmcclient package, it contained the zhmc CLI. Starting with zhmcclient version 0.18.0, the zhmc CLI has been moved from this project into the new zhmccli project.
If your project uses the zhmc CLI, and you are upgrading the zhmcclient package from before 0.18.0 to 0.18.0 or later, your project will need to add the zhmccli package to its dependencies.
1.2. Supported environments¶
The zhmcclient package is supported in these environments:
- Operating systems: Linux, Windows, OS-X
- Python versions: 2.7, 3.4, and higher 3.x
- HMC versions: 2.11.1 and higher
The following table shows for each HMC version the supported HMC API version and the supported IBM Z machine generations. The corresponding LinuxONE machine generations are listed in the notes below the table:
HMC version | HMC API version | HMC API book | Machine generations |
---|---|---|---|
2.11.1 | 1.1 - 1.2 | HMC API 2.11.1 | z196 and z114 |
2.12.0 | 1.3 | HMC API 2.12.0 | z196 to zEC12 and z114 |
2.12.1 | 1.4 - 1.5 | HMC API 2.12.1 | z196 to zEC12 and z114 to zBC12 |
2.13.0 | 1.6 | HMC API 2.13.0 | z196 to z13 (1) and z114 to zBC12 |
2.13.1 | 1.7, 2.1 - 2.2 | HMC API 2.13.1 | z196 to z13 (1) and z114 to z13s (2) |
2.14.0 (5) | 2.20 - 2.24 | HMC API 2.14.0 | z196 to z14 (3) and z114 to z14-ZR1 (4) |
Notes:
- Supported for z13 and LinuxONE Emperor
- Supported for z13s and LinuxONE Rockhopper
- Supported for z14 and LinuxONE Emperor II
- Supported for z14-ZR1 and LinuxONE Rockhopper II
- HMC version 2.14.0 supports both the first and second wave of machines; there is no 2.14.1 numbered HMC version anymore.
1.3. Installation¶
The easiest way to install the zhmcclient package is by using Pip. Pip ensures that any dependent Python packages also get installed.
With Pip, there are three options for where to install a Python package and its dependent packages:
Into a virtual Python environment. This is done by having the virtual Python environment active, and running the Pip install commands as shown in the following sections.
This option is recommended if you intend to develop programs using the zhmcclient API, because the packages you install do not interfere with other Python projects you may have.
Into the system Python, just for the current user. This is done by not having a virtual Python environment active, and by using the
--user
option on the Pip install commands shown in the following sections.This option is recommended if you intend to only use the zhmc CLI, or if you are not concerned about interfering with other Python projects you may have.
Into the system Python, for all users of the system. This is done by not having a virtual Python environment active, and by using
sudo
on the Pip install commands shown in the following sections.Be aware that this option will replace the content of existing Python packages, e.g. when a package version is updated. Such updated packages as well as any newly installed Python 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.3.1. Installation of latest released version¶
The following command installs the latest released version of the zhmcclient package from Pypi into the currently active Python environment:
$ pip install zhmcclient
1.3.2. Installation of latest development version¶
If you want to install the latest development level of the zhmcclient package
instead for some reason, you can install directly from the master
branch
of its Git repository.
The following command installs the latest development level of the zhmcclient package into the currently active Python environment:
$ pip install git+https://github.com/zhmcclient/python-zhmcclient.git@master
1.3.3. Installation on a system without Internet access¶
In both cases described above, Internet access is needed to access these repositories.
If you want to install the zhmcclient package on a system that does not have Internet access, you can do this by first downloading the zhmcclient package and its dependent packages on a download system that does have Internet access, transferring these packages to the target system, and installing them on the target system from the downloaded packages:
On a system with Internet access, download the zhmcclient package and its dependent packages:
[download-system]$ mkdir packages [download-system]$ cd packages [download-system]$ pip download zhmcclient Collecting zhmcclient Using cached https://files.pythonhosted.org/packages/c3/29/7f0acab22b27ff29453ac87c92a2cbec2b16014b0d32c36fcce1ca285be7/zhmcclient-0.19.0-py2.py3-none-any.whl Saved ./zhmcclient-0.19.0-py2.py3-none-any.whl Collecting stomp.py>=4.1.15 (from zhmcclient) . . . Successfully downloaded zhmcclient stomp.py pytz requests decorator six pbr docopt idna urllib3 certifi chardet [download-system]$ ls -1 certifi-2018.4.16-py2.py3-none-any.whl chardet-3.0.4-py2.py3-none-any.whl decorator-4.3.0-py2.py3-none-any.whl docopt-0.6.2.tar.gz idna-2.6-py2.py3-none-any.whl pbr-4.0.2-py2.py3-none-any.whl pytz-2018.4-py2.py3-none-any.whl requests-2.18.4-py2.py3-none-any.whl six-1.11.0-py2.py3-none-any.whl stomp.py-4.1.20.tar.gz urllib3-1.22-py2.py3-none-any.whl zhmcclient-0.19.0-py2.py3-none-any.whl
Transfer all downloaded package files to the target system. Note that the package files are binary files.
The actual files you see in your directory may not be the same ones shown in this section, because new package versions may have been released meanwhile, and new versions may even have different dependent packages.
On the target system, install the zhmcclient package in a way that causes Pip not to go out to the Pypi repository on the Internet, and instead resolves its dependencies by using the packages you transferred from the download system into the current directory:
[target-system]$ ls -1 certifi-2018.4.16-py2.py3-none-any.whl chardet-3.0.4-py2.py3-none-any.whl decorator-4.3.0-py2.py3-none-any.whl docopt-0.6.2.tar.gz idna-2.6-py2.py3-none-any.whl pbr-4.0.2-py2.py3-none-any.whl pytz-2018.4-py2.py3-none-any.whl requests-2.18.4-py2.py3-none-any.whl six-1.11.0-py2.py3-none-any.whl stomp.py-4.1.20.tar.gz urllib3-1.22-py2.py3-none-any.whl zhmcclient-0.19.0-py2.py3-none-any.whl [target-system]$ pip install -f . --no-index --upgrade zhmcclient-*.whl Looking in links: . Processing ./zhmcclient-0.19.0-py2.py3-none-any.whl Collecting six>=1.10.0 (from zhmcclient==0.19.0) . . . Installing collected packages: six, pytz, idna, urllib3, certifi, chardet, requests, decorator, docopt, stomp.py, pbr, zhmcclient Successfully installed certifi-2018.4.16 chardet-3.0.4 decorator-4.3.0 docopt-0.6.2 idna-2.6 pbr-4.0.2 pytz-2018.4 requests-2.18.4 six-1.11.0 stomp.py-4.1.20 urllib3-1.22 zhmcclient-0.19.0
1.3.4. Verification of the installation¶
You can verify that the zhmcclient package and its dependent packages are installed correctly by importing the package into Python:
$ python -c "import zhmcclient; print('ok')"
ok
1.4. Setting up the HMC¶
Usage of the zhmcclient package requires that the HMC in question is prepared accordingly:
The Web Services API must be enabled on the HMC.
To use all functionality provided in the zhmcclient package, the HMC user ID that will be used by the zhmcclient must be authorized for the following tasks. The description of each method of the zhmcclient package will mention its specific authorization requirements.
- “Remote Restart” must be enabled on the HMC
- Use of the Web Services API
- Shutdown/Restart
- Manage Alternate HMC
- Audit and Log Management
- View Security Logs
- Manage LDAP Server Definitions
- Manage Password Rules
- Manage Users
- Manage User Patterns
- Manage User Roles
- Manage User Templates
When using CPCs in DPM mode:
- Start (a CPC in DPM mode)
- Stop (a CPC in DPM mode)
- New Partition
- Delete Partition
- Partition Details
- Start Partition
- Stop Partition
- Dump Partition
- PSW Restart (a Partition)
- Create HiperSockets Adapter
- Delete HiperSockets Adapter
- Adapter Details
- Manage Adapters
- Export WWPNs
When using CPCs in classic mode (or ensemble mode):
- Activate (an LPAR)
- Deactivate (an LPAR)
- Load (an LPAR)
- Customize/Delete Activation Profiles
- CIM Actions ExportSettingsData
(Optional) If desired, the HMC user ID that will be used by the zhmcclient can be restricted to accessing only certain resources managed by the HMC. To establish such a restriction, create a custom HMC user role, limit resource access for that role accordingly, and associate the HMC user ID with that role.
The zhmcclient needs object-access permission for the following resources:
- CPCs to be accessed
For CPCs in DPM mode:
- Partitions to be accessed
- Adapters to be accessed
For CPCs in classic mode (or ensemble mode):
- LPARs to be accessed
For details, see the HMC Operations Guide.
A step-by-step description for a similar use case can be found in chapter 11, section “Enabling the System z HMC to work the Pacemaker STONITH Agent”, in the KVM for IBM z Systems V1.1.2 System Administration book.
1.5. Examples¶
The following example code lists the machines (CPCs) managed by an HMC:
#!/usr/bin/env python
import zhmcclient
import requests.packages.urllib3
requests.packages.urllib3.disable_warnings()
# Set these variables for your environment:
hmc_host = "<IP address or hostname of the HMC>"
hmc_userid = "<userid on that HMC>"
hmc_password = "<password of that HMC userid>"
session = zhmcclient.Session(hmc_host, hmc_userid, hmc_password)
client = zhmcclient.Client(session)
cpcs = client.cpcs.list()
for cpc in cpcs:
print(cpc)
Possible output when running the script:
Cpc(name=P000S67B, object-uri=/api/cpcs/fa1f2466-12df-311a-804c-4ed2cc1d6564, status=service-required)
For more example code, see the Python scripts in the examples directory of the Git repository, or the Tutorials section of this documentation.
1.6. Versioning¶
This documentation applies to version 0.20.0 of the zhmcclient package. You can also see that version in the top left corner of this page.
The zhmcclient package uses the rules of Semantic Versioning 2.0.0 for its version.
The package version can be accessed by programs using the
zhmcclient.__version__
variable [1]:
-
zhmcclient._version.
__version__
= '0.20.0'¶ The full version of this package including any development levels, as a string.
Possible formats for this version string are:
- “M.N.P.devD”: Development level D of a not yet released assumed M.N.P version
- “M.N.P”: A released M.N.P version
This documentation may have been built from a development level of the package. You can recognize a development version of this package by the presence of a “.devD” suffix in the version string. Development versions are pre-versions of the next assumed version that is not yet released. For example, version 0.1.2.dev25 is development pre-version #25 of the next version to be released after 0.1.1. Version 1.1.2 is an assumed next version, because the actually released next version might be 0.2.0 or even 1.0.0.
[1] | For tooling reasons, that variable is shown as
zhmcclient._version.__version__ in this documentation, but it should be
accessed as zhmcclient.__version__ . |
1.7. Compatibility¶
In this package, compatibility is always seen from the perspective of the user of the package. Thus, a backwards compatible new version of this package means that the user can safely upgrade to that new version without encountering compatibility issues.
This package uses the rules of Semantic Versioning 2.0.0 for compatibility between package versions, and for deprecations.
The public API of this package that is subject to the semantic versioning rules (and specificically to its compatibility rules) is the API described in this documentation.
Violations of these compatibility rules are described in section Change log.
1.8. Deprecations¶
Deprecated functionality is marked accordingly in this documentation and in the
Change log, and is made visible at runtime by issuing Python warnings of
type DeprecationWarning
(see warnings
for
details).
Since Python 2.7, DeprecationWarning
warnings 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
by issuing in your Python program:
warnings.filterwarnings(action='default', category=DeprecationWarning)
It is recommended that users of this package run their test code with
DeprecationWarning
warnings being shown, so they become
aware of any use of deprecated functionality.
It is even possible to raise an exception instead of issuing a warning message
upon the use of deprecated functionality, by setting the action to 'error'
instead of 'default'
.
1.9. Reporting issues¶
If you encounter any problem with this package, or if you have questions of any kind related to this package (even when they are not about a problem), please open an issue in the zhmcclient issue tracker.
1.10. License¶
This package is licensed under the Apache 2.0 License.