zhmcclient - A pure Python client library for the IBM Z HMC Web Services API
Introduction
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.
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.
Supported environments
The zhmcclient package is supported in these environments:
Operating systems: Linux, Windows (native, and with UNIX-like environments), OS-X
Python versions: 2.7, 3.5, 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 |
z196 and z114 |
|
2.12.0 |
1.3 |
z196 to zEC12 and z114 |
|
2.12.1 |
1.4 - 1.5 |
z196 to zEC12 and z114 to zBC12 |
|
2.13.0 |
1.6 |
z196 to z13 (1) and z114 to zBC12 |
|
2.13.1 |
1.7, 2.1 - 2.2 |
z196 to z13 (1) and z114 to z13s (2) |
|
2.14.0 |
2.20 - 2.25 |
z196 to z14 (3) and z114 to z13s (2) |
|
2.14.1 |
2.35 - 2.40 |
z196 to z14 (3) and z114 to z14-ZR1 (4) |
|
2.15.0 |
3.1 - 3.4 |
z196 to z15 (5) 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
Supported for z15 and LinuxONE III
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.
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
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:
$ pip install git+https://github.com/zhmcclient/python-zhmcclient.git@master#egg=zhmcclient
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 decorator pytz stomp.py six requests docopt urllib3 certifi chardet idna [download-system]$ ls -1 certifi-2019.11.28-py2.py3-none-any.whl chardet-3.0.4-py2.py3-none-any.whl decorator-4.4.1-py2.py3-none-any.whl docopt-0.6.2.tar.gz idna-2.8-py2.py3-none-any.whl pytz-2019.3-py2.py3-none-any.whl requests-2.22.0-py2.py3-none-any.whl six-1.13.0-py2.py3-none-any.whl stomp.py-4.1.22.tar.gz urllib3-1.25.7-py2.py3-none-any.whl zhmcclient-0.25.1-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-2019.11.28-py2.py3-none-any.whl chardet-3.0.4-py2.py3-none-any.whl decorator-4.4.1-py2.py3-none-any.whl docopt-0.6.2.tar.gz idna-2.8-py2.py3-none-any.whl pytz-2019.3-py2.py3-none-any.whl requests-2.22.0-py2.py3-none-any.whl six-1.13.0-py2.py3-none-any.whl stomp.py-4.1.22.tar.gz urllib3-1.25.7-py2.py3-none-any.whl zhmcclient-0.25.1-py2.py3-none-any.whl [target-system]$ pip install -f . --no-index --upgrade zhmcclient-*.whl Looking in links: . . . . Installing collected packages: decorator, pytz, docopt, stomp.py, six, urllib3, certifi, chardet, idna, requests, zhmcclient Successfully installed certifi-2019.11.28 chardet-3.0.4 decorator-4.4.1 docopt-0.6.2 idna-2.8 pytz-2019.3 requests-2.22.0 six-1.13.0 stomp.py-4.1.22 urllib3-1.25.7 zhmcclient-0.25.1
Alternative installation methods and sources
The installation using Pip as shown in the previous sections uses the wheel distribution archive from Pypi. This is the fastest installation method and source and does not normally need to be changed.
In case you have a need to install from alternative sources, or cannot use Pip for some reason, here are some alternative installation methods and sources:
Pip install from wheel distribution archive (the normal case discussed earlier):
$ pip install zhmcclient
Pip install from source distribution archive:
# Download the source dist archive (you can also use any other means to get it): $ pip download zhmcclient --no-binary zhmcclient # Install from the source dist archive: $ pip install zhmcclient-0.26.1.tar.gz # adjust version
setup.py install from unpacked source distribution archive:
# Download the source dist archive (you can also use any other means to get it): $ pip download zhmcclient --no-binary zhmcclient # Install from the source dist archive: $ tar -xf zhmcclient-0.26.1.tar.gz # adjust version $ python setup.py install
Pip install from repo root directory:
$ git clone https://github.com/zhmcclient/python-zhmcclient $ cd python-zhmcclient $ pip install .
setup.py install from repo root directory:
$ git clone https://github.com/zhmcclient/python-zhmcclient $ cd python-zhmcclient $ python setup.py install
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
Considerations for Windows
On Windows, you can run your Python scripts on native Windows or in a UNIX-like environment (such as CygWin, MSYS2, Babun, or Gow).
Running Python scripts on native Windows means they run in the Windows command processor, and use a Python installed on Windows.
Running Python scripts in a UNIX-like environment means they run in the shell of the UNIX-like environment, and use the Python of the UNIX-like environment.
The zhmcclient package can be used in any of these scenarios. It is tested on the Appveyor CI on native Windows, with CygWin and with MSYS2.
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.
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.
Versioning
This documentation applies to version 1.1.1 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__ = '1.1.1'
The full version of this package including any development levels, as a string.
Possible formats for this version string are:
“M.N.P.dev1”: A not yet released version M.N.P
“M.N.P”: A released version M.N.P
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 aszhmcclient.__version__
.
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.
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 exceptions.DeprecationWarning
(see warnings
for
details).
Since Python 2.7, exceptions.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
exceptions.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'
.
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.
It is helpful if you include debug information in the issue, that can be printed as in the following example:
$ python -m zhmcclient.debuginfo
Operating system: Darwin 18.7.0 on x86_64
Python implementation: CPython 3.8.2 (64 bit, wide unicode)
Python version: 3.8.2
zhmcclient version: 0.27.0.dev1
License
This package is licensed under the Apache 2.0 License.
Tutorials
This section contains tutorials explaining the use of the zhmcclient package.
Each tutorial is a Jupyter Notebook (formerly known as IPython Notebook). In order to view a tutorial, just click on a link in the table below. This will show the tutorial in the online Jupyter Notebook Viewer.
Tutorial |
Short description |
---|---|
1: Basics about Jupyter notebooks |
|
2: Connecting to an HMC |
|
3: Basics about working with HMC resources |
|
4: Error handling |
Executing code in the tutorials
In order to execute and also modify the code in the tutorials, Jupyter Notebook needs to be installed in a Python environment, preferrably in a virtual Python environment, and you need to have the notebook files locally.
There are two options on how to do that:
Set up the development environment for zhmcclient (see Setting up the development environment). This will provide you with an installation of Jupyter Notebook and with all the tutorial notebooks in directory
docs/notebooks
.To start Jupyter Notebook with all tutorial notebooks, issue from the repo work directory:
$ jupyter notebook --notebook-dir=docs/notebooks
If you intend to keep your changes locally, you may want to work on a copy of the
docs/notebooks
directory that is outside of the repo work directory.Install Jupyter Notebook and the zhmcclient package into a Python environment (preferrably virtual):
$ pip install jupyter zhmcclient
and download the tutorial notebooks using the download button in the Jupyter Notebook Viewer (following the links in the table above).
To start Jupyter Notebook with the downloaded tutorial notebooks, issue:
$ jupyter notebook --notebook-dir={your-notebook-dir}
Concepts
This section presents some concepts that are helpful to understand when using the zhmcclient package.
Topology
The following figure shows the topology of Python applications using the zhmcclient package with an HMC and the CPCs managed by that HMC:
+----------------------------------------+ +--------------------+
| Node 1 | | Node 2 |
| | | |
| +----------------+ +--------------+ | | +--------------+ |
| | Python app 1 | | Python app 2 | | | | Python app 3 | |
| +----------------+ +--------------+ | | +--------------+ |
| | zhmcclient | | zhmcclient | | | | zhmcclient | |
| | S S NR | | S NR | | | | S | |
| +-v------v---^---+ +----v--^------+ | | +-----v--------+ |
+----|------|---|-----------|--|---------+ +--------|-----------+
| | | | | |
REST| REST| |JMS REST| |JMS REST|
| | | | | |
+----v------v---^-----------v--^---------------------v-----------+
| |
| HMC |
| |
| ... resources ... |
| |
+-------------+------------------------------------+-------------+
| |
| |
+-------------+------------+ +-------------+-------------+
| | | |
| CPC 1 | | CPC 2 |
| | | |
| ... resources ... | | ... resources ... |
| | | |
+--------------------------+ +---------------------------+
The Python applications can be for example the
zhmc
CLI (provided in the zhmccli project), your own Python
scripts using the zhmcclient API, or long-lived services that perform some
function. In any case, each Python application in the figure runs in the
runtime of exactly one Python process.
In that Python process, exactly one instance of the zhmcclient Python package
is loaded. Performing HMC operations on a particular HMC requires a
Session
object (shown as S
in the figure). Receiving
notifications from a particular HMC requires a
NotificationReceiver
object (shown as NR
in the
figure).
For example, Python app 1 in the figure has two sessions and one notification receiver. For simplicity, the two sessions go to the same HMC in this example, but they could also go to different HMCs. Similarly, a Python app could receive notifications from more than one HMC.
Multi-threading considerations
The zhmcclient package supports the use of multi-threading in Python processes,
but each Session
, Client
, and
NotificationReceiver
object can be used by only one thread
at a time. However, this is not verified or enforced by the zhmcclient package,
so ensuring this is a responsibility of the user of the zhmcclient package.
If your Python app is multi-threaded, it is recommended that each thread with a
need to perform HMC operations has its own Session
object
and its own Client
object, and that each thread with a
need to receive HMC notifications has its own
NotificationReceiver
object. These different objects can
very well target the same HMC.
Resource model concepts
The zhmcclient package provides a resource model at its API that represents exactly the resource model described in the HMC API book. Some of these resources are located on the HMC (for example HMC users), and some on the CPCs managed by the HMC (for example the CPC itself, or partitions on the CPC).
The entry points for a user of the zhmcclient API are two objects that need to be created by the user:
a
Session
object. A session object represents a REST session with exactly one HMC and handles all aspects of the session, such as the credentials for automatic logon and re-logon, the retry and timeout configuration, or the logging configuration.a
Client
object. A client object is the top of the resource tree and is initialized with aSession
object (if connecting to a real HMC) or with aFakedSession
object (in unit tests that work against a mocked HMC). Despite its classname, a client object really represents the HMC (real or mocked).
A session that is logged on is always in the context of the HMC userid that was used for the session. That HMC userid determines what the Python application using that session object can see and what it is allowed to do. See Setting up the HMC for a list of access rights that are needed in order to see all resources and to perform all tasks supported by the zhmcclient package. The HMC API book details for each HMC operation which access rights are needed in order to perform the operation.
A client object is the top of the resource tree exposed by an HMC. Resources
located on the HMC (e.g. HMC userids) are direct or indirect children of the
client object. The CPCs managed by the HMC are direct children of the client
object, and the resources located on each CPC are direct or indirect children
of the Cpc
object representing the CPC. There is a strict
parent-child relationship in the resource model, so that the resource model is
a strict tree without any shared children.
For each actual managed resource on the HMC or its managed CPCs, the
zhmcclient package may provide more than one Python object representing that
resource. For example, the child resources of a resource can be listed by
using the list()
method. Each time that method is
invoked, it returns a new list of Python objects representing the state of
the child resources at the time the call was made.
This is an important principle in the design of the zhmcclient API: Whenever a
Python object representing a resource (i.e. objects of subclasses of
BaseResource
) is returned to the caller of the zhmcclient
API, its state represents the state of the actual managed resource at the time
the call was made, but the state of the Python resource object is not
automatically being updated when the state of the actual managed resource
changes.
As a consequence, there are multiple Python resource objects for the same actual managed resource.
All Python resource objects provided by the zhmcclient package can be asked to
update their state to match the current state of the actual managed resource,
via the pull_full_properties()
method.
Alternatively, a new Python resource object with the current state of the
actual managed resource can be retrieved using the
find()
method using filters on name or object ID
so that only the desired single resource is returned. See Filtering for
details.
With the exception of the Client
object, Python resource
objects are never created by the user of the zhmcclient package. Instead, they
are always returned back to the user. Most of the time, resource objects are
returned from methods such as list()
,
find()
or
findall()
. They are methods on a manager object
that handles the set of child resources of a particular type within a parent
resource. For example, the Client
object has a
cpcs
instance attribute of type
CpcManager
which handles the CPCs managed by the HMC.
Invoking list()
returns the CPCs managed by
the HMC as Cpc
resource objects. Each
Cpc
object has again instance attributes for its child
resources, for example its partitions
instance attribute
of type PartitionManager
handles the set of partitions of
that CPC (but not the partitions of other CPCs managed by this HMC).
See Reference: Resources for a description of the resource model supported by the zhmcclient package.
Error handling
Errors are returned to the user by raising exceptions. All exception classes
defined in the zhmcclient package are derived from zhmcclient.Error
.
Exceptions may be raised that are not derived from Error
.
In all cases where this is possible, this is very likely caused by programming
errors of the user (incorrect type passed in, invalid value passed in, etc.).
Some HTTP status code / reason code combinations returned from the HMC are silently handled by the zhmcclient package:
GET, POST, or DELETE with status 403 and reason 5: This combination means that the HMC session token has expired. It is handled by re-logon, creating a new session token, and retrying the original HMC operation.
POST with status 202: This status code means that the operation is being performed asynchronously. There are two cases for that:
If there is a response body, an asynchronous job has been started on the HMC that performs the actual operation. If
wait_for_completion
isTrue
in the method that invoked the HMC operation, the method waits for completion of the job (via polling with GET on the job URI), gathering success or failure from the job results. In case of success, the job results are returned from the method. In case of failure, anHTTPError
is raised based upon the error information in the job results.If there is no response body, the operation is performed asynchronously on the HMC, but there is no job resource that can be used to poll for completion status. This is used only for operations such as restarting the HMC.
The other HTTP status / reason code combinations are forwarded to the user by
means of raising HTTPError
. That exception class is
modeled after the error information described in section “Error response
bodies” of the HMC API book.
The exception classes defined in the zhmcclient package are described in section Exceptions.
Filtering
The resource lookup methods on manager objects support the concept of resource filtering. This concept allows narrowing the set of returned resources based upon the matching of filter arguments.
The methods that support resource filtering, are:
A resource is included in the result only if it matches all filter arguments (i.e. this is a logical AND between the filter arguments).
A filter argument specifies a property name and a match value.
Any resource property may be specified in a filter argument. The zhmcclient implementation handles them in an optimized way: Properties that can be filtered on the HMC are actually filtered there (this varies by resource type), and the remaining properties are filtered on the client side.
For the findall()
and
find()
methods, an additional optimization is
implemented: If the “name” property is specified as the only filter argument,
an optimized lookup is performed that uses a name-to-URI cache in this manager
object.
The match value specifies how the corresponding resource property matches:
For resource properties of type String (as per the resource’s data model in the HMC API), the match value is interpreted as a regular expression that must match the actual resource property value. The regular expression syntax used is the same as that used by the Java programming language, as specified for the
java.util.regex.Pattern
class (see http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html).For resource properties of type String Enum, the match value is interpreted as an exact string that must be equal to the actual resource property value.
For resource properties of other types, the match value is interpreted as an exact value that must be equal to the actual resource property value.
If the match value is a list or a tuple, a resource matches if any item in the list or tuple matches (i.e. this is a logical OR between the list items).
If a property that is specified in filter arguments does not exist on all resources that are subject to be searched, those resources that do not have the property are treated as non-matching. An example for this situation is the “card-location” property of the Adapter resource which does not exist for Hipersocket adapters.
Examples:
This example uses the
findall()
method to return those OSA adapters in cage ‘1234’ of a given CPC, whose state is ‘stand-by’, ‘reserved’, or ‘unknown’:filter_args = { 'adapter-family': 'osa', 'card-location': '1234-.*', 'state': ['stand-by', 'reserved', 'unknown'], } osa_adapters = cpc.adapters.findall(**filter_args)
The returned resource objects will have only a minimal set of properties.
This example uses the
list()
method to return the same set of OSA adapters as the previous example, but the returned resource objects have the full set of properties:osa_adapters = cpc.adapters.list(full_properties=True, filter_args=filter_args)
This example uses the
find()
method to return the adapter with a given adapter name:adapter1 = cpc.adapters.find(name='OSA-1')
The returned resource object will have only a minimal set of properties.
This example uses the
find()
method to return the adapter with a given object ID:oid = '12345-abc...-def-67890' adapter1 = cpc.adapters.find(**{'object-id':oid})
The returned resource object will have only a minimal set of properties.
Auto-updating of resources
The resource objects returned by the zhmcclient library support auto-updating of resource properties.
By default, auto-updating is disabled for any resource objects, and the user can
use the pull_full_properties()
method to have the
properties of the resource object updated explicitly.
If auto-updating is enabled for a resource object (by means of
enable_auto_update()
), the zhmcclient library
subscribes on the HMC for object notifications that inform the client about
changes to resource properties. When receiving such notifications, the client
updates the properties on the local resource objects that are enabled for
auto-updating, to the new values.
There is only one subscription at the HMC for each zhmcclient session that has auto-updating enabled, so if auto-updating is enabled for a second and further resource objects, the already existing subscription is used. When disabling auto-updating, the last resource that is disabled will unsubscribe at the HMC.
The subscription for object notifications will cause the following notifications to be sent from the HMC to the client:
property change notifications for any properties that have the property-change (pc) qualifier set, for all resources,
status change notifications for any properties that have the status-change (sc) qualifier set, for all resources,
inventory change notifications for any resources that come into existence or go out of existence.
The auto-update support in zhmcclient processes the property and status change notifications by updating the correponding properties in those resource objects that have been enabled for auto-updating. As a result, these properties will always have the value the resource object has on the HMC.
The auto-update support in zhmcclient ignores property and status change notifications for resource objects that have not been enabled for auto-updating and it also ignores inventory change notifications.
The delay for the new property value to become visible in the zhmcclient resource object after it has been changed on the HMC, is in the order of 1 second.
Note that accessing the properties of a zhmcclient resource object is not any slower when auto-update is enabled - the auto-update happens asynchronously to the access, and depending on whether the access happens before or after an auto-update, you get the old or new value.
Example:
cpc = ... # A zhmcclient.Cpc object
partition_name = 'PART1'
# Two different zhmcclient.Partition objects representing the same partition on the HMC
partition1 = cpc.partitions.find(name=partition_name)
partition2 = cpc.partitions.find(name=partition_name)
assert id(partition1) != id(partition2)
partition1.enable_auto_update() # Enable auto-update for this partition object
prop_name = 'description'
while True:
value1 = partition1.prop(prop_name)
value2 = partition2.prop(prop_name)
print("Property '{}' of objects 1: {!r}, 2: {!r}".
format(prop_name, value1, value2))
sleep(1)
This example creates two different partition objects representing the same partition on the HMC. It enables auto-update for one of the partition objects but not for the other, in order to show the different behavior.
The example then prints the value of the ‘description’ property of both partition objects in a loop, so that in parallel, a change of the description of the partition can be performed on the HMC (not shown in the example).
Once the description of the partition on the HMC is changed, the partition object that has auto-update enabled will show the new value, while the other one will show the same value unchanged:
Property 'description' of objects 1: 'foo', 2: 'foo'
Property 'description' of objects 1: 'foo', 2: 'foo'
Property 'description' of objects 1: 'foo', 2: 'foo'
# description property is changed to 'bar' on the HMC
Property 'description' of objects 1: 'bar', 2: 'foo'
Property 'description' of objects 1: 'bar', 2: 'foo'
Property 'description' of objects 1: 'bar', 2: 'foo'
Reference: General features
Session
Session class: A session to the HMC, optionally in context of an HMC user.
- class zhmcclient.Session(host, userid=None, password=None, session_id=None, get_password=None, retry_timeout_config=None, port=6794, verify_cert=True)[source]
A session to the HMC, optionally in context of an HMC user.
The session supports operations that require to be authenticated, as well as operations that don’t (e.g. obtaining the API version).
The session can keep statistics about the elapsed time for issuing HTTP requests against the HMC API. Instance variable
time_stats_keeper
is used to enable/disable the measurements, and to print the statistics.Creating a session object will not immediately cause a logon to be attempted; the logon is deferred until needed.
There are several alternatives for specifying the authentication related parameters:
userid/password only: The session is initially in a logged-off state and subsequent operations that require logon will use the specified userid and password to automatically log on. The returned session-id will be stored in this session object. Subsequent operations that require logon will use that session-id. Once the HMC expires that session-id, subsequent operations that require logon will cause a re-logon with the specified userid and password.
userid/password and session_id: The specified session-id will be stored in this session object, so that the session is initially in a logged-on state. Subsequent operations that require logon will use that session-id. Once the HMC expires that session-id, subsequent operations that require logon will cause a re-logon with the specified userid/password.
session_id only: The specified session-id will be stored in this session object, so that the session is initially in a logged-on state. Subsequent operations that require logon will use the stored session-id. Once the HMC expires the session-id, subsequent operations that require logon will cause an
ServerAuthError
to be raised (because userid/password have not been specified, so an automatic re-logon is not possible).Neither userid/password nor session_id: Only operations that do not require logon, are possible.
- Parameters
host (string) – HMC host. For valid formats, see the
host
property. Must not be None.userid (string) – Userid of the HMC user to be used, or None.
password (string) – Password of the HMC user to be used, if userid was specified.
session_id (string) – Session-id to be used for this session, or None.
get_password (callable) –
A password retrieval function, or None.
If provided, this function will be called if a password is needed but not provided. This mechanism can be used for example by command line interfaces for prompting for the password.
The password retrieval function must follow the interface defined in
get_password_interface()
.retry_timeout_config (
RetryTimeoutConfig
) –The retry/timeout configuration for this session for use by any of its HMC operations, overriding any defaults.
None for an attribute in that configuration object means that the default value will be used for that attribute.
None for the entire retry_timeout_config parameter means that a default configuration will be used with the default values for all of its attributes.
See Constants for the default values.
port (integer) – HMC TCP port. Defaults to
DEFAULT_HMC_PORT
. For details, see theport
property.verify_cert (bool or string) –
Controls whether and how the client verifies the server certificate presented by the HMC during SSL/TLS handshake:
False: Do not verify the HMC certificate. Not verifying the HMC certificate means the zhmcclient will not detect hostname mismatches, expired certificates, revoked certificates, or otherwise invalid certificates. Since this mode makes the connection vulnerable to man-in-the-middle attacks, it is insecure and should not be used in production environments.
True: Verify the HMC certificate using the CA certificates from the first of these locations:
The file or directory in the REQUESTS_CA_BUNDLE env.var, if set
The file or directory in the CURL_CA_BUNDLE env.var, if set
The Python ‘certifi’ package (which contains the Mozilla Included CA Certificate List).
string: Path name of a certificate file or directory. Verify the HMC certificate using the CA certificates in that file or directory.
For details, see the HMC certificate section.
Added in version 0.31
Methods:
__repr__
()Return a string with the state of this session, for debug purposes.
logon
([verify])Make sure the session is logged on to the HMC.
logoff
([verify])Make sure the session is logged off from the HMC.
is_logon
([verify])Return a boolean indicating whether the session is currently logged on to the HMC.
get
(uri[, logon_required])Perform the HTTP GET method against the resource identified by a URI.
post
(uri[, body, logon_required, ...])Perform the HTTP POST method against the resource identified by a URI, using a provided request body.
delete
(uri[, logon_required])Perform the HTTP DELETE method against the resource identified by a URI.
The 'Get Notification Topics' operation returns a structure that describes the JMS notification topics associated with the API session.
Return whether this session is currently subscribed for auto-updating of resources.
Subscribe this session for auto-updating of resources, if not currently subscribed.
Unsubscribe this session from auto-updating of resources, if currently subscribed.
Attributes:
HMC host, in one of the following formats:
HMC TCP port to be used.
Userid of the HMC user to be used.
Controls whether and how the client verifies server certificate presented by the HMC during SSL/TLS handshake.
The password retrieval function, or None.
The effective retry/timeout configuration for this session for use by any of its HMC operations, taking into account the defaults and the session-specific overrides.
Base URL of the HMC in this session.
HTTP headers to be used in each request.
The time statistics keeper (for a usage example, see section Time Statistics).
Session ID for this session, returned by the HMC.
requests.Session
object for this session.Name of the notification topic the HMC will use to send object-related notification messages to this API session.
Name of the notification topic the HMC will use to send job notification messages to this API session.
Resource updater for auto-updating of resources.
- property host
HMC host, in one of the following 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
- Type
- property userid
Userid of the HMC user to be used.
If None, only operations that do not require authentication, can be performed.
- Type
- property verify_cert
Controls whether and how the client verifies server certificate presented by the HMC during SSL/TLS handshake.
For details, see the same-named init parameter.
- Type
bool or string
- property get_password
The password retrieval function, or None.
The password retrieval function must follow the interface defined in
get_password_interface()
.
- property retry_timeout_config
The effective retry/timeout configuration for this session for use by any of its HMC operations, taking into account the defaults and the session-specific overrides.
- Type
- property base_url
Base URL of the HMC in this session.
Example:
https://myhmc.acme.com:6794
- Type
- property headers
HTTP headers to be used in each request.
Initially, this is the following set of headers:
Content-type: application/json Accept: */*
When the session is logged on to the HMC, the session token is added to these headers:
X-API-Session: ...
- Type
- property time_stats_keeper
The time statistics keeper (for a usage example, see section Time Statistics).
- property object_topic
Name of the notification topic the HMC will use to send object-related notification messages to this API session.
When not logged on, this property is None.
The associated topic type is “object-notification”.
- Type
- property job_topic
Name of the notification topic the HMC will use to send job notification messages to this API session.
When not logged on, this property is None.
The associated topic type is “job-notification”.
- Type
- property resource_updater
Resource updater for auto-updating of resources.
- Type
- logon(verify=False)[source]
Make sure the session is logged on to the HMC.
By default, this method checks whether there is a session-id set and considers that sufficient for determining that the session is logged on. The verify parameter can be used to verify the validity of a session-id that is already set, by issuing a dummy operation (“Get Console Properties”) to the HMC.
After successful logon to the HMC, the following is stored in this session object for reuse in subsequent operations:
the HMC session-id, in order to avoid extra userid authentications,
a
requests.Session
object, in order to enable connection pooling. Connection pooling avoids repetitive SSL/TLS handshakes.
- Parameters
verify (bool) – If a session-id is already set, verify its validity.
- Raises
- logoff(verify=False)[source]
Make sure the session is logged off from the HMC.
After successful logoff, the HMC session-id and
requests.Session
object stored in this object are reset.- Parameters
verify (bool) – If a session-id is already set, verify its validity.
- Raises
- is_logon(verify=False)[source]
Return a boolean indicating whether the session is currently logged on to the HMC.
By default, this method checks whether there is a session-id set and considers that sufficient for determining that the session is logged on. The verify parameter can be used to verify the validity of a session-id that is already set, by issuing a dummy operation (“Get Console Properties”) to the HMC.
- Parameters
verify (bool) – If a session-id is already set, verify its validity.
- get(uri, logon_required=True)[source]
Perform the HTTP GET method against the resource identified by a URI.
A set of standard HTTP headers is automatically part of the request.
If the HMC session token is expired, this method re-logs on and retries the operation.
- Parameters
uri (string) – Relative URI path of the resource, e.g. “/api/session”. This URI is relative to the base URL of the session (see the
base_url
property). Must not be None.logon_required (bool) – Boolean indicating whether the operation requires that the session is logged on to the HMC. For example, the API version retrieval operation does not require that.
- Returns
json object with the operation result.
- Raises
- post(uri, body=None, logon_required=True, wait_for_completion=False, operation_timeout=None)[source]
Perform the HTTP POST method against the resource identified by a URI, using a provided request body.
A set of standard HTTP headers is automatically part of the request.
HMC operations using HTTP POST are either synchronous or asynchronous. Asynchronous operations return the URI of an asynchronously executing job that can be queried for status and result.
Examples for synchronous operations:
With no result: “Logon”, “Update CPC Properties”
With a result: “Create Partition”
Examples for asynchronous operations:
With no result: “Start Partition”
The wait_for_completion parameter of this method can be used to deal with asynchronous HMC operations in a synchronous way.
If executing the operation reveals that the HMC session token is expired, this method re-logs on and retries the operation.
The timeout and retry
- Parameters
uri (string) – Relative URI path of the resource, e.g. “/api/session”. This URI is relative to the base URL of the session (see the
base_url
property). Must not be None.body (json object or string or file-like object) – The HTTP request body (payload). If a JSON object (=dict) is provided, it will be serialized into a UTF-8 encoded binary string. If a Unicode string is provided, it will be encoded into a UTF-8 encoded binary string. If a binary string is provided, it will be used unchanged. If a file-like object is provided, it must return binary strings, i.e. the file must have been opened in binary mode. None means the same as an empty dictionary, namely that no HTTP body is included in the request.
logon_required (bool) – Boolean indicating whether the operation requires that the session is logged on to the HMC. For example, the “Logon” operation does not require that.
wait_for_completion (bool) –
Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation.
A value of True will cause an additional entry in the time statistics to be created that represents the entire asynchronous operation including the waiting for its completion. That time statistics entry will have a URI that is the targeted URI, appended with “+completion”.
For synchronous HMC operations, this parameter has no effect on the operation execution or on the return value of this method, but it should still be set (or defaulted) to False in order to avoid the additional entry in the time statistics.
operation_timeout (number) –
Timeout in seconds, when waiting for completion of an asynchronous operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used.
For wait_for_completion=True, a
OperationTimeout
is raised when the timeout expires.For wait_for_completion=False, this parameter has no effect.
- Returns
A json object or None or a
Job
object, as follows:For synchronous HMC operations, and for asynchronous HMC operations with wait_for_completion=True:
If this method returns, the HMC operation has completed successfully (otherwise, an exception is raised). For asynchronous HMC operations, the associated job has been deleted.
The return value is the result of the HMC operation as a json object, or None if the operation has no result. See the section in the HMC API book about the specific HMC operation for a description of the members of the returned JSON object.
For asynchronous HMC operations with wait_for_completion=False:
If this method returns, the asynchronous execution of the HMC operation has been started successfully as a job on the HMC (if the operation could not be started, an exception is raised).
The return value is a
Job
object representing the job on the HMC.
- Raises
OperationTimeout – The timeout expired while waiting for completion of the asynchronous operation.
TypeError – Body has invalid type.
- delete(uri, logon_required=True)[source]
Perform the HTTP DELETE method against the resource identified by a URI.
A set of standard HTTP headers is automatically part of the request.
If the HMC session token is expired, this method re-logs on and retries the operation.
- Parameters
uri (string) – Relative URI path of the resource, e.g. “/api/session/{session-id}”. This URI is relative to the base URL of the session (see the
base_url
property). Must not be None.logon_required (bool) – Boolean indicating whether the operation requires that the session is logged on to the HMC. For example, for the logoff operation, it does not make sense to first log on.
- Raises
- get_notification_topics()[source]
The ‘Get Notification Topics’ operation returns a structure that describes the JMS notification topics associated with the API session.
- Returns
A list with one item for each notification topic. Each item is a dictionary with the following keys:
"topic-type"
(string): Topic type, e.g. “job-notification”."topic-name"
(string): Topic name; can be used for subscriptions."object-uri"
(string): When topic-type is “os-message-notification”, this item is the canonical URI path of the Partition for which this topic exists. This field does not exist for the other topic types."include-refresh-messages"
(bool): When the topic-type is “os-message-notification”, this item indicates whether refresh operating system messages will be sent on this topic.
- auto_update_subscribed()[source]
Return whether this session is currently subscribed for auto-updating of resources.
- Returns
Indicates whether session is subscribed.
- Return type
- subscribe_auto_update()[source]
Subscribe this session for auto-updating of resources, if not currently subscribed.
When subscribed, object notifications will be sent by the HMC as resource objects on the HMC change their properties or come or go. These object notifications will be received by the client and will then update the properties of any Python resource objects that are enabled for auto-updating.
This method is automatically called by
enable_auto_update()
and thus does not need to be called by the user.
- unsubscribe_auto_update()[source]
Unsubscribe this session from auto-updating of resources, if currently subscribed.
When unsubscribed, object notifications are no longer sent by the HMC.
This method is automatically called by
disable_auto_update()
and thus does not need to be called by the user.
- class zhmcclient.Job(session, uri, op_method, op_uri)[source]
A job on the HMC that performs an asynchronous HMC operation.
This class supports checking the job for completion, and waiting for job completion.
- Parameters
session (
Session
) – Session with the HMC. Must not be None.uri (string) –
Canonical URI of the job on the HMC. Must not be None.
Example:
"/api/jobs/{job-id}"
op_method (string) –
Name of the HTTP method of the operation that is executing asynchronously on the HMC. Must not be None.
Example:
"POST"
op_uri (string) –
Canonical URI of the operation that is executing asynchronously on the HMC. Must not be None.
Example:
"/api/partitions/{partition-id}/stop"
Attributes:
Session with the HMC.
Canonical URI of the job on the HMC.
Name of the HTTP method of the operation that is executing asynchronously on the HMC.
Canonical URI of the operation that is executing asynchronously on the HMC.
Methods:
Check once for completion of the job and return completion status and result if it has completed.
wait_for_completion
([operation_timeout])Wait for completion of the job, then delete the job on the HMC and return the result of the original asynchronous HMC operation, if it completed successfully.
- property op_method
Name of the HTTP method of the operation that is executing asynchronously on the HMC.
Example:
"POST"
- Type
- property op_uri
Canonical URI of the operation that is executing asynchronously on the HMC.
Example:
"/api/partitions/{partition-id}/stop"
- Type
- check_for_completion()[source]
Check once for completion of the job and return completion status and result if it has completed.
If the job completed in error, an
HTTPError
exception is raised.- Returns
A tuple (status, result) with:
status (string): Completion status of the job, as returned in the
status
field of the response body of the “Query Job Status” HMC operation, as follows:"complete"
: Job completed (successfully).any other value: Job is not yet complete.
result (json object or None): None for incomplete jobs. For completed jobs, the result of the original asynchronous operation that was performed by the job, from the
job-results
field of the response body of the “Query Job Status” HMC operation. That result is a json object as described for the asynchronous operation, or None if the operation has no result.
- Raises
HTTPError – The job completed in error, or the job status cannot be retrieved, or the job cannot be deleted.
- wait_for_completion(operation_timeout=None)[source]
Wait for completion of the job, then delete the job on the HMC and return the result of the original asynchronous HMC operation, if it completed successfully.
If the job completed in error, an
HTTPError
exception is raised.- Parameters
operation_timeout (number) –
Timeout in seconds, when waiting for completion of the job. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used.
If the timeout expires, a
OperationTimeout
is raised.This method gives completion of the job priority over strictly achieving the timeout. This may cause a slightly longer duration of the method than prescribed by the timeout.
- Returns
The result of the original asynchronous operation that was performed by the job, from the
job-results
field of the response body of the “Query Job Status” HMC operation. That result is a json object as described for the asynchronous operation, or None if the operation has no result.- Return type
json object or None
- Raises
HTTPError – The job completed in error, or the job status cannot be retrieved, or the job cannot be deleted.
OperationTimeout – The timeout expired while waiting for job completion.
- zhmcclient.get_password_interface(host, userid)[source]
Interface to the password retrieval function that is invoked by
Session
if no password is provided.- Parameters
host (string) – Hostname or IP address of the HMC
userid (string) – Userid on the HMC
- Returns
Password of the userid on the HMC
- Return type
string
Retry / timeout configuration
- class zhmcclient.RetryTimeoutConfig(connect_timeout=None, connect_retries=None, read_timeout=None, read_retries=None, max_redirects=None, operation_timeout=None, status_timeout=None, name_uri_cache_timetolive=None)[source]
A configuration setting that specifies verious retry counts and timeout durations.
For all parameters, None means that this object does not specify a value for the parameter, and that a default value should be used (see Constants).
All parameters are available as instance attributes.
- Parameters
connect_timeout (number) – Connect timeout in seconds. This timeout applies to making a connection at the socket level. The same socket connection is used for sending an HTTP request to the HMC and for receiving its HTTP response. The special value 0 means that no timeout is set.
connect_retries (integer) – Number of retries (after the initial attempt) for connection-related issues. These retries are performed for failed DNS lookups, failed socket connections, and socket connection timeouts.
read_timeout (number) – Read timeout in seconds. This timeout applies to reading at the socket level, when receiving an HTTP response. The special value 0 means that no timeout is set.
read_retries (integer) – Number of retries (after the initial attempt) for read-related issues. These retries are performed for failed socket reads and socket read timeouts. A retry consists of resending the original HTTP request. The zhmcclient restricts these retries to just the HTTP GET method. For other HTTP methods, no retry will be performed.
max_redirects (integer) – Maximum number of HTTP redirects.
operation_timeout (number) – Asynchronous operation timeout in seconds. This timeout applies when waiting for the completion of asynchronous HMC operations. The special value 0 means that no timeout is set.
status_timeout (number) – Resource status timeout in seconds. This timeout applies when waiting for the transition of the status of a resource to a desired status. The special value 0 means that no timeout is set.
name_uri_cache_timetolive (number) – Time to the next automatic invalidation of the Name-URI cache of manager objects, in seconds since the last invalidation. The special value 0 means that no Name-URI cache is maintained (i.e. the caching is disabled).
Methods:
override_with
(override_config)Return a new configuration object that represents the configuration from this configuration object acting as a default, and the specified configuration object overriding that default.
- override_with(override_config)[source]
Return a new configuration object that represents the configuration from this configuration object acting as a default, and the specified configuration object overriding that default.
- Parameters
override_config (
RetryTimeoutConfig
) – The configuration object overriding the defaults defined in this configuration object.- Returns
A new configuration object representing this configuration object, overridden by the specified configuration object.
- Return type
ResourceUpdater
Resource updater for auto-updating of resources.
- class zhmcclient.ResourceUpdater(session)[source]
A class that updates the properties of zhmcclient resource objects that are enabled for auto-updating.
Experimental: This class is considered experimental at this point, and its API may change incompatibly as long as it is experimental.
Note: The user should not create any objects of this class nor invoke any methods of this class, because the objects are created automatically when a
Session
object is subscribed for auto-update (via itssubscribe_auto_update()
method).Creating an object of this class establishes a JMS session with the HMC and subscribes for the object notification topic of the session. This causes the HMC to emit status notifications, property notifications, and inventory notifications, which are processed by this class and cause the properties of zhmcclient resource objects to be updated that are registered to this class as a result of enabling auto-update for the resorce object (via their
enable_auto_update()
method).Zhmcclient resource objects that are not enabled for auto-updating remain unchanged.
- Parameters
session (
Session
) – Session for which the resource updater should do its work. This defines the HMC host and credentials that are used to establish the JMS session with the HMC.
Methods:
close
()Disconnect and close the JMS session with the HMC.
register_object
(resource_obj)Register a resource object to this resource updater.
unregister_object
(resource_obj)Unregister a resource object from this resource updater.
registered_objects
(resource_uri)Generator that yields the resource objects for the specified URI.
Return boolean indicating whether there are any resource objects registered.
- close()[source]
Disconnect and close the JMS session with the HMC.
This implicitly unsubscribes from the object notification topic this updater was created for.
- register_object(resource_obj)[source]
Register a resource object to this resource updater.
If this resource object (by id) is already registered, nothing is done.
- unregister_object(resource_obj)[source]
Unregister a resource object from this resource updater.
If this resource object (by id) is already unregistered, nothing is done.
Client
Client class: A client to an HMC.
- class zhmcclient.Client(session)[source]
A client to an HMC.
This is the main class for users of this package.
- Parameters
session (
Session
) – Session with the HMC.
Attributes:
Session
: Session with the HMC.CpcManager
: Manager object for the CPCs in scope of this client.ConsoleManager
: Manager object for the (one) Console representing the HMC this client is connected to.MetricsContextManager
: Manager object for the Metrics Contexts in scope of this client (i.e.Methods:
Returns API version information for the HMC.
The Query API Version operation returns information about the level of Web Services API supported by the HMC.
get_inventory
(resources)Returns a JSON object with the requested resources and their properties, that are managed by the HMC.
wait_for_available
([operation_timeout])Wait for the Console (HMC) this client is connected to, to become available.
- property cpcs
CpcManager
: Manager object for the CPCs in scope of this client. This includes managed and unmanaged CPCs.
- property consoles
ConsoleManager
: Manager object for the (one) Console representing the HMC this client is connected to.
- property metrics_contexts
MetricsContextManager
: Manager object for the Metrics Contexts in scope of this client (i.e. in scope of its HMC).
- version_info()[source]
Returns API version information for the HMC.
This operation does not require authentication.
- Returns
The HMC API version supported by the HMC.
- Return type
- Raises
- query_api_version()[source]
The Query API Version operation returns information about the level of Web Services API supported by the HMC.
This operation does not require authentication.
- Returns
A JSON object with members
api-major-version
,api-minor-version
,hmc-version
andhmc-name
. For details about these properties, see section ‘Response body contents’ in section ‘Query API Version’ in the HMC API book.- Return type
- Raises
- get_inventory(resources)[source]
Returns a JSON object with the requested resources and their properties, that are managed by the HMC.
This method performs the ‘Get Inventory’ HMC operation.
- Parameters
resources (iterable of string) –
Resource classes and/or resource classifiers specifying the types of resources that should be included in the result. For valid values, see the ‘Get Inventory’ operation in the HMC API book.
Element resources of the specified resource types are automatically included as children (for example, requesting ‘partition’ includes all of its ‘hba’, ‘nic’ and ‘virtual-function’ element resources).
Must not be None.
- Returns
- The list of resources for the requested resource
classes and resource classifiers. Each list item is a dictionary with the resource properties using the HMC property names.
- Return type
list of dict
Example
resource_classes = [‘partition’, ‘adapter’] resource_list = client.get_inventory(resource_classes)
- Raises
- wait_for_available(operation_timeout=None)[source]
Wait for the Console (HMC) this client is connected to, to become available. The Console is considered available if the
query_api_version()
method succeeds.If the Console does not become available within the operation timeout, an
OperationTimeout
exception is raised.- Parameters
operation_timeout (number) –
Timeout in seconds, when waiting for the Console to become available. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used.
If the timeout expires, a
OperationTimeout
is raised.- Raises
OperationTimeout – The timeout expired while waiting for the Console to become available.
Time Statistics
The TimeStatsKeeper
class allows measuring the elapsed
time of accordingly instrumented code and keeps a statistics of these times.
The Session
class uses this class for keeping
statistics about the time to issue HTTP requests against the HMC API (see its
time_stats_keeper
property).
The TimeStats
class is a helper class that contains the
actual measurement data for all invocations of a particular HTTP request. Its
objects are under control of the TimeStatsKeeper
class.
Example:
import zhmcclient
session = zhmcclient.Session(hmc, userid, password)
session.time_stats_keeper.enable()
# Some operations that are being measured
client = zhmcclient.Client(session)
cpcs = client.cpcs.list()
print(session.time_stats_keeper)
- class zhmcclient.TimeStatsKeeper[source]
Statistics keeper for elapsed times.
The statistics keeper can hold multiple time statistics (see
TimeStats
), that are identified by a name.The statistics keeper can be in a state of enabled or disabled. If enabled, it accumulates the elapsed times between subsequent calls to the
begin()
andend()
methods of classTimeStats
. If disabled, calls to these methods do not accumulate any time.Initially, the statistics keeper is disabled.
Attributes:
Indicates whether the statistics keeper is enabled.
Methods:
enable
()Enable the statistics keeper.
disable
()Disable the statistics keeper.
get_stats
(name)Get the time statistics for a name.
snapshot
()Return a snapshot of the time statistics of this keeper.
__str__
()Return a human readable string with the time statistics for this keeper.
- property enabled
Indicates whether the statistics keeper is enabled.
- get_stats(name)[source]
Get the time statistics for a name. If a time statistics for that name does not exist yet, create one.
- Parameters
name (string) – Name of the time statistics.
- Returns
The time statistics for the specified name. If the statistics keeper is disabled, a dummy time statistics object is returned, in order to save resources.
- Return type
- snapshot()[source]
Return a snapshot of the time statistics of this keeper.
The snapshot represents the statistics data at the time this method is called, and remains unchanged even if the statistics of this keeper continues to be updated.
- Returns
A dictionary of the time statistics by operation, where:
- Return type
- __str__()[source]
Return a human readable string with the time statistics for this keeper. The operations are sorted by decreasing average time.
Example result, if keeper is enabled:
Time statistics (times in seconds): Count Average Minimum Maximum Operation name 1 0.024 0.024 0.024 get /api/cpcs 1 0.009 0.009 0.009 get /api/version
- class zhmcclient.TimeStats(keeper, name)[source]
Elapsed time statistics for all invocations of a particular named operation.
All invocations of the operation will be accumulated into the statistics data kept by an object of this class.
Objects of this class don’t need to (and in fact, are not supposed to) be created by the user. Instead, the
zhmcclient.TimeStatsKeeper.get_stats()
method should be used to create objects of this class.- Parameters
keeper (TimeStatsKeeper) – The statistics keeper that holds this time statistics.
name (string) – Name of the operation.
Attributes:
Name of the operation this time statistics has data for.
The time statistics keeper holding this time statistics.
The number of invocations of the operation.
The average elapsed time for invoking the operation, in seconds.
The minimum elapsed time for invoking the operation, in seconds.
The maximum elapsed time for invoking the operation, in seconds.
Methods:
reset
()Reset the time statistics data for the operation.
begin
()This method must be called before invoking the operation.
end
()This method must be called after the operation returns.
__str__
()Return a human readable string with the time statistics for this operation.
- property name
Name of the operation this time statistics has data for.
This name is used by the
TimeStatsKeeper
object holding this time statistics as a key.- Type
- property keeper
The time statistics keeper holding this time statistics.
- Type
- begin()[source]
This method must be called before invoking the operation. Note that this method is not to be invoked by the user; it is invoked by the implementation of the
Session
class.If the statistics keeper holding this time statistics is enabled, this method takes the current time, so that
end()
can calculate the elapsed time between the two method calls.If the statistics keeper holding this time statistics is disabled, this method does nothing, in order to save resources.
- end()[source]
This method must be called after the operation returns. Note that this method is not to be invoked by the user; it is invoked by the implementation of the
Session
class.If the statistics keeper holding this time statistics is enabled, this method takes the current time, calculates the duration of the operation since the last call to
begin()
, and updates the time statistics to reflect the new operation.If the statistics keeper holding this time statistics is disabled, this method does nothing, in order to save resources.
If this method is called without a preceding call to
begin()
, aRuntimeError
is raised.- Raises
Metrics
The HMC supports the retrieval of metrics values for resources of a IBM Z or LinuxONE computer. This section describes the zhmcclient API for retrieving such metrics from the HMC.
A resource termed Metrics Context is associated with any metrics retrieval. These resources are user-created definitions of the kinds of metrics that are intended to be retrieved. A metrics context mostly defines the names of the metric groups to be retrieved. The available metric groups are described in section ‘Metric Groups’ in the HMC API book.
The zhmcclient API for metrics provides access to the metric values and to their definitions, so that clients using the metric values do not need to have intimate knowledge about the specific metric values when just displaying them.
The basic usage of the metrics API is shown in this example:
# Create a Metrics Context for the desired metric groups:
metric_groups = ['dpm-system-usage-overview', 'partition-usage']
mc = client.metrics_contexts.create(
{'anticipated-frequency-seconds': 15,
'metric-groups': metric_groups})
# Retrieve the current metric values:
mr_str = mc.get_metrics()
# Display the metric values:
print("Current metric values:")
mr = zhmcclient.MetricsResponse(mc, mr_str)
for mg in mr.metric_group_values:
mg_name = mg.name
mg_def = mc.metric_group_definitions[mg_name]
print(" Metric group: {}".format(mg_name))
for ov in mg.object_values:
print(" Resource: {}".format(ov.resource_uri))
print(" Timestamp: {}".format(ov.timestamp))
print(" Metric values:")
for m_name in ov.metrics:
m_value = ov.metrics[m_name]
m_def = mg_def.metric_definitions[m_name]
m_unit = m_def.unit or ''
print(" {:30} {} {}".format(m_name, m_value, m_unit))
if not mg.object_values:
print(" No resources")
# Delete the Metrics Context:
mc.delete()
- class zhmcclient.MetricsContextManager(client)[source]
Manager providing access to the Metrics Context resources that were created through this manager object.
Derived from
BaseManager
; see there for common methods and attributes.Objects of this class are not directly created by the user; they are accessible via the
metrics_contexts
attribute of theClient
object connected to the HMC.Methods:
__repr__
()Return a string with the state of this manager object, for debug purposes.
list
([full_properties])List the Metrics Context resources that were created through this manager object.
create
(properties)Create a Metrics Context resource in the HMC this client is connected to.
find
(**filter_args)Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g.
find_by_name
(name)Find a resource by name (i.e.
find_local
(name, uri[, properties])Return a local resource object without fetching it from the HMC.
findall
(**filter_args)Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g.
flush
()Invalidate the Name-URI cache of this manager.
invalidate_cache
()Invalidate the Name-URI cache of this manager.
resource_object
(uri_or_oid[, props])Return a minimalistic Python resource object for this resource class, that is scoped to this manager.
Attributes:
Client
: The client defining the scope for this manager.class_name
The resource class name
parent
Subclass of
BaseResource
: Parent resource defining the scope for this manager.resource_class
The Python class of the parent resource of this manager.
session
Session
: Session with the HMC.- list(full_properties=False)[source]
List the Metrics Context resources that were created through this manager object.
Note that the HMC does not provide a way to enumerate the existing Metrics Context resources. Therefore, this method will only list the Metrics Context resources that were created through this manager object. For example, Metrics Context resources created through a second
Client
object will not be listed.- Parameters
full_properties (bool) – This parameter exists for compatibility with other resource classes, but for this class, it has no effect on the result.
- Returns
A list of
MetricsContext
objects.- Raises
- create(properties)[source]
Create a Metrics Context resource in the HMC this client is connected to.
- Parameters
properties (dict) – Initial property values. Allowable properties are defined in section ‘Request body contents’ in section ‘Create Metrics Context’ in the HMC API book.
- Returns
The resource object for the new Metrics Context resource.
- Return type
- Raises
- class zhmcclient.MetricsContext(manager, uri, name=None, properties=None)[source]
Representation of a Metrics Context resource.
A Metrics Context resource specifies a list of metrics groups for which the current metric values can be retrieved using the
get_metrics()
method.The properties of this resource are the response fields described for the ‘Create Metrics Context’ operation in the HMC API book.
This class is derived from
BaseResource
; see there for common methods and attributes.Objects of this class can be created by the user with the
zhmcclient.MetricsContextManager.create()
method.Attributes:
The metric definitions for the metric groups of this Metrics Context resource, as a dictionary of
MetricGroupDefinition
objects, by metric group name.full_properties
A boolean indicating whether or not the resource properties in this object are the full set of resource properties.
manager
Subclass of
BaseManager
: Manager object for this resource (and for all resources of the same type in the scope of that manager).name
The name of the resource.
properties
The properties of this resource that are currently present in this Python object, as a dictionary.
properties_timestamp
The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).
uri
The canonical URI path of the resource.
Methods:
Retrieve the current metric values for this Metrics Context resource from the HMC.
delete
()Delete this Metrics Context resource.
__repr__
()Return a string with the state of this resource, for debug purposes.
__str__
()Return a human readable string representation of this resource.
auto_update_enabled
()Return whether auto-update is currently enabled for the resource object.
disable_auto_update
()Disable auto-update for this resource object, if currently enabled.
enable_auto_update
()Enable auto-update for this resource object, if currently disabled.
get_properties_local
(names[, defaults])Return the values of a set of resource properties, using default values for those that are not present in this Python object, without retrieving them from the HMC.
get_property
(name)Return the value of a resource property.
prop
(name[, default])Return the value of a resource property, applying a default if it does not exist.
pull_full_properties
()Retrieve the full set of resource properties and cache them in this object.
update_properties_local
(properties)Update the values of a set of resource properties on this Python object without propagating the updates the HMC.
- property metric_group_definitions
The metric definitions for the metric groups of this Metrics Context resource, as a dictionary of
MetricGroupDefinition
objects, by metric group name.- Type
- get_metrics()[source]
Retrieve the current metric values for this Metrics Context resource from the HMC.
The metric values are returned by this method as a string in the MetricsResponse format described with the ‘Get Metrics’ operation in the HMC API book.
The
MetricsResponse
class can be used to process the MetricsResponse string returned by this method, and provides structured access to the metrics values.- Returns
The current metric values, in the MetricsResponse string format.
- Return type
- Raises
- delete()[source]
Delete this Metrics Context resource.
- Raises
- class zhmcclient.MetricGroupDefinition(name, resource_class, metric_definitions)[source]
A
namedtuple
representing definitional information for a metric group.- Parameters
name (string) – Metric group name, as defined in section ‘Metric groups’ in the HMC API book.
resource_class (string) – A string identifying the resource class to which this metric group belongs, using the values from the ‘class’ property of resource objects.
metric_definitions (dict) – Metric definitions for the metrics in this metric group, as a dictionary where the key is the metric name and the value is the
MetricDefinition
object for the metric.
All these parameters are also available as same-named attributes.
Methods:
__new__
(cls, name, resource_class, ...)- param name
Metric group name, as defined in section 'Metric groups' in the
count
(value, /)Return number of occurrences of value.
index
(value[, start, stop])Return first index of value.
Attributes:
metric_definitions
Alias for field number 2
name
Alias for field number 0
resource_class
Alias for field number 1
- static __new__(cls, name, resource_class, metric_definitions)[source]
- Parameters
name (string) – Metric group name, as defined in section ‘Metric groups’ in the HMC API book.
resource_class (string) – A string identifying the resource class to which this metric group belongs, using the values from the ‘class’ property of resource objects.
metric_definitions (dict) – Metric definitions for the metrics in this metric group, as a dictionary where the key is the metric name and the value is the
MetricDefinition
object for the metric.
All these parameters are also available as same-named attributes.
- class zhmcclient.MetricDefinition(index, name, type, unit)[source]
A
namedtuple
representing definitional information for a single metric.- Parameters
index (integer) – 0-based index (=position) of the metric in a MetricsResponse value row.
name (string) – Metric field name, as shown in the tables defining the metric groups in section ‘Metric groups’ in the HMC API book.
type (callable) –
Python type for the metric value. The type must be a constructor (callable) that takes the metrics value from the MetricsResponse string as its only argument, using the following Python types for the metric group description types shown in the HMC API book:
Description type
Python type
Boolean
Byte
Short
Integer
Long
Double
String, String Enum
unit (string) – Unit of the metric value.
All these parameters are also available as same-named attributes.
Methods:
__new__
(cls, index, name, type, unit)- param index
0-based index (=position) of the metric in a MetricsResponse value
count
(value, /)Return number of occurrences of value.
Attributes:
index
Alias for field number 0
name
Alias for field number 1
type
Alias for field number 2
unit
Alias for field number 3
- static __new__(cls, index, name, type, unit)[source]
- Parameters
index (integer) – 0-based index (=position) of the metric in a MetricsResponse value row.
name (string) – Metric field name, as shown in the tables defining the metric groups in section ‘Metric groups’ in the HMC API book.
type (callable) –
Python type for the metric value. The type must be a constructor (callable) that takes the metrics value from the MetricsResponse string as its only argument, using the following Python types for the metric group description types shown in the HMC API book:
Description type
Python type
Boolean
Byte
Short
Integer
Long
Double
String, String Enum
unit (string) – Unit of the metric value.
All these parameters are also available as same-named attributes.
- class zhmcclient.MetricsResponse(metrics_context, metrics_response_str)[source]
Represents the metric values returned by one call to the
get_metrics()
method, and provides structured access to the data.- Parameters
metrics_context (
MetricsContext
) – TheMetricsContext
object that was used to retrieve the metrics response string. It defines the structure of the metric values in the metrics response string.metrics_response_str (string) – The metrics response string, as returned by the
get_metrics()
method.
Attributes:
MetricsContext
object for this metric response.The list of
MetricGroupValues
objects representing the metric groups in this metric response.- property metrics_context
MetricsContext
object for this metric response. This can be used to access the metric definitions for this response.
- property metric_group_values
The list of
MetricGroupValues
objects representing the metric groups in this metric response.Each
MetricGroupValues
object contains a list ofMetricObjectValues
objects representing the metric values in this group (each for a single resource and point in time).- Type
- class zhmcclient.MetricGroupValues(name, object_values)[source]
Represents the metric values for a metric group in a MetricsResponse string.
- Parameters
name (string) – Metric group name.
object_values (
list
) – TheMetricObjectValues
objects in this metric group. Each of them represents the metric values for a single resource at a single point in time.
Attributes:
The metric group name.
The
MetricObjectValues
objects in this metric group.- property name
The metric group name.
- Type
string
- property object_values
The
MetricObjectValues
objects in this metric group. Each of them represents the metric values for a single resource at a single point in time.- Type
- class zhmcclient.MetricObjectValues(client, metric_group_definition, resource_uri, timestamp, metrics)[source]
Represents the metric values for a single resource at a single point in time.
- Parameters
client (
Client
) – Client object, for retrieving the actual resource.metric_group_definition (
MetricGroupDefinition
) – Metric group definition for this set of metric values.resource_uri (string) – Resource URI of the resource these metric values apply to.
timestamp (
datetime.datetime
) – Point in time when the HMC captured these metric values (as a timezone-aware datetime object).metrics (dict) – The metric values, as a dictionary of the (Python typed) metric values, by metric name.
Attributes:
Client object, for retrieving the actual resource.
Metric group definition for this set of metric values.
The canonical URI path of the resource these metric values apply to.
Point in time when the HMC captured these metric values (as a timezone-aware datetime object).
The metric values, as a dictionary of the (Python typed) metric values, by metric name.
The Python resource object of the
- property metric_group_definition
Metric group definition for this set of metric values.
- property resource_uri
The canonical URI path of the resource these metric values apply to.
Example:
/api/cpcs/12345
- Type
string
- property timestamp
Point in time when the HMC captured these metric values (as a timezone-aware datetime object).
- Type
- property metrics
The metric values, as a dictionary of the (Python typed) metric values, by metric name.
- Type
- property resource
- The Python resource object of the
resource these metric values apply to.
- Raises
MetricsResourceNotFound – The resource for the
resource URI of the resource these metric values apply to, was not –
found on the HMC. –
- Type
Logging
The zhmcclient supports logging using the standard Python logging
module, using standard Python Logger
objects with these
names:
‘zhmcclient.api’ for user-issued calls to zhmcclient API functions, at the debug level. Internal calls to API functions are not logged.
‘zhmcclient.hmc’ for operations from zhmcclient to the HMC, at the debug level.
‘zhmcclient.jms’ for notifications from the HMC to zhmcclient, at the debug, info, warning and error level. At this point, this logger is used only for the auto-update support, but not for the
NotificationReceiver
class.
For HMC operations and API calls that contain the HMC password or HMC session tokens, the password is hidden in the log message by replacing it with a few ‘*’ characters.
All these loggers have a null-handler (see NullHandler
)
and have no log formatter (see Formatter
).
As a result, the loggers are silent by default. If you want to turn on logging,
add a log handler (see addHandler()
, and
logging.handlers
for the handlers included with Python) and set the
log level (see setLevel()
, and Logging Levels for
the defined levels).
If you want to change the default log message format, use
setFormatter()
. Its form
parameter is a format
string with %-style placeholders for the log record attributes (see Python
section LogRecord attributes).
Examples:
To output the log records for all HMC operations to
stdout
in a particular format, do this:import logging handler = logging.StreamHandler() format_string = '%(asctime)s - %(name)s - %(levelname)s - %(message)s' handler.setFormatter(logging.Formatter(format_string)) logger = logging.getLogger('zhmcclient.hmc') logger.addHandler(handler) logger.setLevel(logging.DEBUG)
This example uses the
basicConfig()
convenience function that sets the same format and level as in the previous example, but for the root logger. Therefore, it will output all log records, not just from this package:import logging format_string = '%(asctime)s - %(name)s - %(levelname)s - %(message)s' logging.basicConfig(format=format_string, level=logging.DEBUG)
Exceptions
Exceptions that can be raised by the client.
- class zhmcclient.Error[source]
Abstract base class for exceptions specific to this package.
Exceptions of this class are not raised; only derived exceptions are raised.
Derived from
exceptions.Exception
.Methods:
str_def
()Interface definition for the corresponding method derived exception classes.
__str__
()Return str(self).
with_traceback
Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.
- class zhmcclient.ConnectionError(msg, details)[source]
This exception indicates a problem with the connection to the HMC, below the HTTP level. HTTP errors are indicated via
HTTPError
.A retry by the user code is not likely to be successful, unless connect or read retries had been disabled when creating the session (see
Session
).Even though this class has exceptions derived from it, exceptions of this class may also be raised (if no other derived class matches the circumstances).
Derived from
Error
.- Parameters
args[0]
will be set to themsg
parameter.Attributes:
The original exception caught by this package, providing more information about the problem.
Methods:
__repr__
()Return a string with the state of this exception object, for debug purposes.
str_def
()string: The exception as a string in a Python definition-style format, e.g.
__str__
()Return str(self).
with_traceback
Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.
- property details
The original exception caught by this package, providing more information about the problem.
This will be one of the following exceptions:
Any exception derived from
requests.exceptions.RequestException
.
- class zhmcclient.ConnectTimeout(msg, details, connect_timeout, connect_retries)[source]
This exception indicates that a connection to the HMC timed out after exhausting the connect retries (see
zhmcclient.RetryTimeoutConfig.connect_retries
).Further retrying by the user code is not likely to be successful, unless connect retries had been disabled when creating the session (see
Session
).Derived from
ConnectionError
.- Parameters
args[0]
will be set to themsg
parameter.Attributes:
The connect timeout in seconds.
The number of connect retries.
details
The original exception caught by this package, providing more information about the problem.
Methods:
__repr__
()Return a string with the state of this exception object, for debug purposes.
str_def
()string: The exception as a string in a Python definition-style format, e.g.
__str__
()Return str(self).
with_traceback
Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.
- class zhmcclient.ReadTimeout(msg, details, read_timeout, read_retries)[source]
This exception indicates that reading an HTTP response from the HMC timed out after exhausting the read retries (see
zhmcclient.RetryTimeoutConfig.read_retries
).Further retrying by the user code is not likely to be successful, unless read retries had been disabled when creating the session (see
Session
).Derived from
ConnectionError
.- Parameters
args[0]
will be set to themsg
parameter.Attributes:
The read timeout in seconds.
The number of read retries.
details
The original exception caught by this package, providing more information about the problem.
Methods:
__repr__
()Return a string with the state of this exception object, for debug purposes.
str_def
()string: The exception as a string in a Python definition-style format, e.g.
__str__
()Return str(self).
with_traceback
Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.
- class zhmcclient.RetriesExceeded(msg, details, connect_retries)[source]
This exception indicates that the maximum number of retries for connecting to the HMC, sending HTTP requests or reading HTTP responses was exceeded, for reasons other than connect timeouts (see
ConnectTimeout
) or read timeouts (seeReadTimeout
).Further retrying by the user code is not likely to be successful, unless connect or read retries had been disabled when creating the session (see
Session
).Derived from
ConnectionError
.- Parameters
args[0]
will be set to themsg
parameter.Attributes:
The number of connect retries.
details
The original exception caught by this package, providing more information about the problem.
Methods:
__repr__
()Return a string with the state of this exception object, for debug purposes.
str_def
()string: The exception as a string in a Python definition-style format, e.g.
__str__
()Return str(self).
with_traceback
Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.
- class zhmcclient.AuthError[source]
This exception indicates erors related to authentication.
Exceptions of this class are not raised; only derived exceptions are raised.
Derived from
Error
.Methods:
__str__
()Return str(self).
str_def
()Interface definition for the corresponding method derived exception classes.
with_traceback
Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.
- class zhmcclient.ClientAuthError(msg)[source]
This exception indicates an authentication related problem detected on the client side.
Derived from
AuthError
.- Parameters
msg (string) – A human readable message describing the problem.
args[0]
will be set to themsg
parameter.Methods:
__repr__
()Return a string with the state of this exception object, for debug purposes.
str_def
()string: The exception as a string in a Python definition-style format, e.g.
__str__
()Return str(self).
with_traceback
Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.
- class zhmcclient.ServerAuthError(msg, details)[source]
This exception indicates an authentication error with the HMC.
Derived from
AuthError
.- Parameters
args[0]
will be set to themsg
parameter.Attributes:
The original exception describing details about the error.
Methods:
__repr__
()Return a string with the state of this exception object, for debug purposes.
str_def
()string: The exception as a string in a Python definition-style format, e.g.
__str__
()Return str(self).
with_traceback
Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.
- property details
The original exception describing details about the error.
This may be one of the following exceptions:
- class zhmcclient.ParseError(msg)[source]
This exception indicates a parsing error while processing the JSON payload in a response from the HMC.
Derived from
Error
.The error location within the payload is automatically determined by parsing the error message for the pattern:
: line {line} column {column}
- Parameters
msg (string) –
A human readable message describing the problem.
This should be the message of the ValueError exception raised by methods of the
json.JSONDecoder
class.
args[0]
will be set to themsg
parameter.Attributes:
The 1-based line number of the error location within the JSON payload.
The 1-based column number of the error location within the JSON payload.
Methods:
__repr__
()Return a string with the state of this exception object, for debug purposes.
str_def
()string: The exception as a string in a Python definition-style format, e.g.
__str__
()Return str(self).
with_traceback
Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.
- property line
The 1-based line number of the error location within the JSON payload.
None indicates that the error location is not available.
- Type
- property column
The 1-based column number of the error location within the JSON payload.
None indicates that the error location is not available.
- Type
- class zhmcclient.VersionError(msg, min_api_version, api_version)[source]
This exception indicates that a function of the client requires a minimum HMC API version which is not supported by the HMC.
Derived from
Error
.- Parameters
msg (string) – A human readable message describing the problem.
min_api_version (HMC API version) – The minimum HMC API version required to perform the function that raised this exception.
api_version (HMC API version) – The actual HMC API version supported by the HMC.
args[0]
will be set to themsg
parameter.Attributes:
The minimum HMC API version required to perform the function that raised this exception.
The actual HMC API version supported by the HMC.
Methods:
__repr__
()Return a string with the state of this exception object, for debug purposes.
str_def
()string: The exception as a string in a Python definition-style format, e.g.
__str__
()Return str(self).
with_traceback
Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.
- property min_api_version
The minimum HMC API version required to perform the function that raised this exception.
- Type
- property api_version
The actual HMC API version supported by the HMC.
- Type
- class zhmcclient.HTTPError(body)[source]
This exception indicates that the HMC returned an HTTP response with a bad HTTP status code.
Derived from
Error
.- Parameters
body (json object) – Body of the HTTP error response.
args[0]
will be set to the ‘message’ item of the body, or to None if not present.Attributes:
Numeric HTTP status code (e.g.
Numeric HMC reason code.
Message describing the error.
The HTTP method (DELETE, GET, POST, PUT) that caused this error response.
The URI that caused this error response.
URI query parameters specified on the request.
HTTP headers specified on the request.
Name of the HMC user associated with the API session under which the request was issued.
The request body, in the form of a JSON document.
The complete request body, or some portion of the request body, exactly as it was submitted by the API client program, if the
request_body
property is None.Indicates whether the
request_body_as_string
property contains only part of the request body (True) or the entire request body (False).Internal HMC diagnostic information for the error.
A nested object that provides additional operation-specific error information.
Methods:
__str__
()Return a human readable string representation of this exception object.
__repr__
()Return a string with the state of this exception object, for debug purposes.
str_def
()string: The exception as a string in a Python definition-style format, e.g.
with_traceback
Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.
- property http_status
Numeric HTTP status code (e.g. 500).
See RFC2616 for a list of HTTP status codes and reason phrases.
- Type
- property reason
Numeric HMC reason code.
HMC reason codes provide more details as to the nature of the error than is provided by the HTTP status code. This HMC reason code is treated as a sub-code of the HTTP status code and thus must be used in conjunction with the HTTP status code to determine the error condition.
Standard HMC reason codes that apply across the entire API are described in section ‘Common request validation reason codes’ in the HMC API book. Additional operation-specific reason codes may also be documented in the description of specific API operations in the HMC API book.
The articial reason code 999 is used when the response from the HMC contains an HTML-formatted error message.
- Type
- property message
Message describing the error.
This message is not currently localized.
- Type
- property request_method
The HTTP method (DELETE, GET, POST, PUT) that caused this error response.
- Type
- property request_query_parms
URI query parameters specified on the request.
Each query-parm-info object identifies a single query parameter by its name and includes its value(s).
An empty list, if the request did not specify any query parameters.
- Type
List of query-parm-info objects
- property request_headers
HTTP headers specified on the request.
An empty list, if the request did not specify any HTTP headers.
- Type
header-info object
- property request_authenticated_as
Name of the HMC user associated with the API session under which the request was issued.
None, if the request was issued without an established session or there is no HMC user bound to the session.
- Type
- property request_body
The request body, in the form of a JSON document. Note that, since it is in the form of a JSON document, this may not be exactly what was submitted by the API client program, but it is semantically equivalent.
If the request body could not be parsed or some other error prevented the creation of a JSON document from the request body, this property is None and the request body is instead available in the
request_body_as_string
property.
- property request_body_as_string
The complete request body, or some portion of the request body, exactly as it was submitted by the API client program, if the
request_body
property is None. Otherwise, None.The
request_body_as_string_partial
property indicates whether the complete request body is provided in this property.- Type
- property request_body_as_string_partial
Indicates whether the
request_body_as_string
property contains only part of the request body (True) or the entire request body (False). None, if therequest_body_as_string
property is None.- Type
- property stack
Internal HMC diagnostic information for the error.
This field is supplied only on selected 5xx HTTP status codes. None, if not supplied.
- Type
- property error_details
A nested object that provides additional operation-specific error information. This field is provided by selected operations, and the format of the nested object is as described by that operation.
- Type
- class zhmcclient.OperationTimeout(msg, operation_timeout)[source]
This exception indicates that the waiting for completion of an asynchronous HMC operation has timed out.
Derived from
Error
.- Parameters
args[0]
will be set to themsg
parameter.Attributes:
The operation timeout in seconds.
Methods:
__repr__
()Return a string with the state of this exception object, for debug purposes.
str_def
()string: The exception as a string in a Python definition-style format, e.g.
__str__
()Return str(self).
with_traceback
Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.
- class zhmcclient.StatusTimeout(msg, actual_status, desired_statuses, status_timeout)[source]
This exception indicates that the waiting for reaching a desired LPAR or Partition status has timed out.
The possible status values for an LPAR are:
"not-activated"
- The LPAR is not active."not-operating"
- The LPAR is active but no operating system is running in the LPAR."operating"
- The LPAR is active and an operating system is running in the LPAR."exceptions"
- The LPAR or its CPC has one or more unusual conditions.
The possible status values for a Partition are described in the ‘status’ property of the data model for the partition resource in the HMC API book.
Derived from
Error
.- Parameters
msg (string) – A human readable message describing the problem.
actual_status (string) – The actual status (at the point in time when the status timeout expired).
desired_statuses (iterable of string) – The desired status values that were supposed to be reached.
status_timeout (number) – The status timeout (in seconds) that has expired.
args[0]
will be set to themsg
parameter.Attributes:
The actual status (at the point in time when the status timeout expired).
The desired status values that were supposed to be reached.
The status timeout (in seconds) that has expired.
Methods:
__repr__
()Return a string with the state of this exception object, for debug purposes.
str_def
()string: The exception as a string in a Python definition-style format, e.g.
__str__
()Return str(self).
with_traceback
Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.
- property actual_status
The actual status (at the point in time when the status timeout expired).
- Type
- class zhmcclient.NotFound(filter_args, manager)[source]
This exception indicates that a resource was not found.
Derived from
Error
.- Parameters
filter_args (dict) – Dictionary of filter arguments by which the resource was attempted to be found. Keys are the resource property names, values are the match values for that property.
manager (
BaseManager
) –The manager of the resource, in whose scope the resource was attempted to be found.
Must not be None.
args[0]
will be set to an exception message that is automatically constructed from the input parameters.Attributes:
Dictionary of filter arguments by which the resource was attempted to be found.
The manager of the resource, in whose scope the resource was attempted to be found.
Methods:
__repr__
()Return a string with the state of this exception object, for debug purposes.
str_def
()string: The exception as a string in a Python definition-style format, e.g.
__str__
()Return str(self).
with_traceback
Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.
- property filter_args
Dictionary of filter arguments by which the resource was attempted to be found. Keys are the resource property names, values are the match values for that property.
- Type
- property manager
The manager of the resource, in whose scope the resource was attempted to be found.
- Type
- class zhmcclient.NoUniqueMatch(filter_args, manager, resources)[source]
This exception indicates that more than one resource matched the filter arguments.
Derived from
Error
.- Parameters
filter_args (dict) – Dictionary of filter arguments by which the resource was attempted to be found. Keys are the resource property names, values are the match values for that property.
manager (
BaseManager
) –The manager of the resource, in whose scope the resource was attempted to be found.
Must not be None.
resources (iterable of
BaseResource
) –The resources that did match the filter.
Must not be None.
args[0]
will be set to an exception message that is automatically constructed from the input parameters.Attributes:
Dictionary of filter arguments by which the resource was attempted to be found.
The manager of the resource, in whose scope the resource was attempted to be found.
The resources that matched the filter.
List of URIs of the resources that matched the filter.
Methods:
__repr__
()Return a string with the state of this exception object, for debug purposes.
str_def
()string: The exception as a string in a Python definition-style format, e.g.
__str__
()Return str(self).
with_traceback
Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.
- property filter_args
Dictionary of filter arguments by which the resource was attempted to be found. Keys are the resource property names, values are the match values for that property.
- Type
- property manager
The manager of the resource, in whose scope the resource was attempted to be found.
- Type
- property resources
The resources that matched the filter.
- Type
List of
BaseResource
- property resource_uris
List of URIs of the resources that matched the filter.
Constants
Public constants.
These constants are not meant to be changed by the user, they are made available for inspection and documentation purposes only.
For technical reasons, the online documentation shows these constants in the
zhmcclient._constants
namespace, but they are also available in the
zhmcclient
namespace and should be used from there.
- zhmcclient._constants.DEFAULT_CONNECT_TIMEOUT = 30
Default HTTP connect timeout in seconds, if not specified in the
retry_timeout_config
init argument toSession
.
- zhmcclient._constants.DEFAULT_CONNECT_RETRIES = 3
Default number of HTTP connect retries, if not specified in the
retry_timeout_config
init argument toSession
.
- zhmcclient._constants.DEFAULT_HMC_PORT = 6794
Default HMC port number
- zhmcclient._constants.DEFAULT_READ_TIMEOUT = 3600
Default HTTP read timeout in seconds, if not specified in the
retry_timeout_config
init argument toSession
.Note: The default value for this parameter has been increased to a large value in order to mitigate the behavior of the ‘requests’ module to retry HTTP methods even if they are not idempotent (e.g. DELETE). See zhmcclient issue #249.
- zhmcclient._constants.DEFAULT_READ_RETRIES = 0
Default number of HTTP read retries, if not specified in the
retry_timeout_config
init argument toSession
.Note: The default value for this parameter has been set to 0 in order to mitigate the behavior of the ‘requests’ module to retry HTTP methods even if they are not idempotent (e.g. DELETE). See zhmcclient issue #249.
- zhmcclient._constants.DEFAULT_STOMP_PORT = 61612
Default port on which the HMC issues JMS over STOMP messages.
- zhmcclient._constants.DEFAULT_MAX_REDIRECTS = 30
Default max. number of HTTP redirects, if not specified in the
retry_timeout_config
init argument toSession
.
- zhmcclient._constants.DEFAULT_OPERATION_TIMEOUT = 3600
Default timeout in seconds for waiting for completion of an asynchronous HMC operation, if not specified in the
retry_timeout_config
init argument toSession
.This is used as a default value in asynchronous methods on resource objects (e.g.
zhmcclient.Partition.start()
), in thezhmcclient.Job.wait_for_completion()
method, and in the low level methodzhmcclient.Session.post()
.
- zhmcclient._constants.DEFAULT_STATUS_TIMEOUT = 900
Default timeout in seconds for waiting for completion of deferred status changes for LPARs, if not specified in the
retry_timeout_config
init argument toSession
.This is used as a default value in asynchronous methods of the
Lpar
class that change its status (e.g.zhmcclient.Lpar.activate()
)).
- zhmcclient._constants.DEFAULT_NAME_URI_CACHE_TIMETOLIVE = 300
Default time to the next automatic invalidation of the Name-URI cache of manager objects, in seconds since the last invalidation, if not specified in the
retry_timeout_config
init argument toSession
.The special value 0 means that no Name-URI cache is maintained (i.e. the caching is disabled).
- zhmcclient._constants.HMC_LOGGER_NAME = 'zhmcclient.hmc'
Name of the Python logger that logs HMC operations.
- zhmcclient._constants.API_LOGGER_NAME = 'zhmcclient.api'
Name of the Python logger that logs zhmcclient API calls made by the user.
- zhmcclient._constants.HTML_REASON_WEB_SERVICES_DISABLED = 900
Web Services API is not enabled on the HMC.
- Type
HTTP reason code
- zhmcclient._constants.HTML_REASON_OTHER = 999
Other HTML-formatted error response. Note that over time, there may be more specific reason codes introduced for such situations.
- Type
HTTP reason code
Utilities
Utility functions.
- zhmcclient.datetime_from_timestamp(ts, tzinfo=<UTC>)[source]
Convert an HMC timestamp number into a
datetime
object. The resulting object will be timezone-aware and will be represented in the specified timezone, defaulting to UTC.The HMC timestamp number must be non-negative. This means the special timestamp value -1 cannot be represented as datetime and will cause
ValueError
to be raised.The date and time range supported by this function has the following bounds:
The upper bounds is determined by
datetime.datetime.max
and additional limitations, as follows:9999-12-31 23:59:59 UTC, for 32-bit and 64-bit CPython on Linux and OS-X.
3001-01-01 07:59:59 UTC, for 32-bit and 64-bit CPython on Windows, due to a limitation in gmtime() in Visual C++.
2038-01-19 03:14:07 UTC, for some 32-bit Python implementations, due to the Year 2038 problem.
The lower bounds is the UNIX epoch: 1970-01-01 00:00:00 UTC.
- Parameters
ts (timestamp) –
Point in time as an HMC timestamp number.
Must not be None.
tzinfo (
datetime.tzinfo
) –Timezone in which the returned object will be represented. This may be any object derived from
datetime.tzinfo
, including but not limited to objects returned bypytz.timezone()
.Note that this parameter does not affect how the HMC timestamp value is interpreted; i.e. the effective point in time represented by the returned object is not affected. What is affected by this parameter is for example the timezone in which the point in time is shown when printing the returned object.
Must not be None.
- Returns
Point in time as a timezone-aware Python datetime object for the specified timezone.
- Return type
- Raises
- zhmcclient.timestamp_from_datetime(dt)[source]
Convert a
datetime
object into an HMC timestamp number.The date and time range supported by this function has the following bounds:
The upper bounds is
datetime.datetime.max
, as follows:9999-12-31 23:59:59 UTC, for 32-bit and 64-bit CPython on Linux and OS-X.
2038-01-19 03:14:07 UTC, for some 32-bit Python implementations, due to the Year 2038 problem.
The lower bounds is the UNIX epoch: 1970-01-01 00:00:00 UTC.
- Parameters
dt (
datetime
) –Point in time as a Python datetime object. The datetime object may be timezone-aware or timezone-naive. If timezone-naive, the UTC timezone is assumed.
Must not be None.
- Returns
Point in time as an HMC timestamp number.
- Return type
- Raises
Reference: Resources
This section describes the resource model supported by the zhmcclient package.
Note that the zhmcclient package supports only a subset of the resources described in the HMC API book. We will grow the implemented subset over time, and if you find that a particular resource you need is missing, please open an issue in the zhmcclient issue tracker.
See Resource model concepts for a description of the concepts used in representing the resource model.
The resource descriptions in this section do not detail the resource properties. The description of the resource properties of a particular HMC resource type can be found in its “Data model” section in the HMC API book. Each Python resource class mentions the corresponding HMC resource type.
The data types used in these “Data model” sections are represented in Python data types according to the mapping shown in the following table:
HMC API data type |
Python data type |
---|---|
Boolean |
|
Byte, Integer, Long, Short |
|
Float |
|
String, String Enum |
|
Array |
|
Object |
CPCs
A CPC (Central Processor Complex) is a physical IBM Z or LinuxONE computer.
A particular HMC can manage multiple CPCs and can discover other CPCs that are not managed by that HMC. Such other CPCs are called “unmanaged CPCs” and they may or may not be managed by another HMC.
This section describes the interface for managed CPCs using resource class
Cpc
and the corresponding manager class
CpcManager
.
The HMC can manage a range of old and new CPC generations. Some older CPC generations are not capable of supporting the HMC Web Services API; these older CPCs can be managed using the GUI of the HMC, but not through its Web Services API. Therefore, such older CPCs will not be exposed at the HMC Web Services API, and thus will not show up in the API of this Python package.
TODO: List earliest CPC generation that supports the HMC Web Services API.
A CPC can be in any of the following three modes:
DPM mode: Dynamic Partition Manager is enabled for the CPC.
Classic mode: The CPC does not have Dynamic Partition Manager enabled, and is not member of an ensemble.
Ensemble mode: The CPC is member of an ensemble. This Python client does not support the functionality that is specific to ensemble mode.
The functionality supported at the HMC API and thus also for users of this Python client, depends on the mode in which the CPC currently is. If a particular functionality is available only in a specific mode, that is indicated in the description of the functionality.
- class zhmcclient.CpcManager(client)[source]
Manager providing access to the managed CPCs exposed by the HMC this client is connected to.
Derived from
BaseManager
; see there for common methods and attributes.Objects of this class are not directly created by the user; they are accessible via the following instance variable of a
Client
object:Attributes:
Client
: The client defining the scope for this manager.Console
: The Console representing the HMC this CPC is managed by.class_name
The resource class name
parent
Subclass of
BaseResource
: Parent resource defining the scope for this manager.resource_class
The Python class of the parent resource of this manager.
session
Session
: Session with the HMC.Methods:
list
([full_properties, filter_args])List the CPCs managed by the HMC this client is connected to.
__repr__
()Return a string with the state of this manager object, for debug purposes.
find
(**filter_args)Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g.
find_by_name
(name)Find a resource by name (i.e.
find_local
(name, uri[, properties])Return a local resource object without fetching it from the HMC.
findall
(**filter_args)Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g.
flush
()Invalidate the Name-URI cache of this manager.
invalidate_cache
()Invalidate the Name-URI cache of this manager.
resource_object
(uri_or_oid[, props])Return a minimalistic Python resource object for this resource class, that is scoped to this manager.
- property console
Console
: The Console representing the HMC this CPC is managed by.The returned object is cached, so it is looked up only upon first access to this property.
The returned object has only the following properties set:
‘object-uri’
Use
get_property()
orprop()
to access any properties regardless of whether they are already set or first need to be retrieved.
- list(full_properties=False, filter_args=None)[source]
List the CPCs managed by the HMC this client is connected to.
Authorization requirements:
Object-access permission to any CPC to be included in the result.
- Parameters
full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation.
filter_args (dict) –
Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering.
None causes no filtering to happen, i.e. all resources are returned.
- Returns
A list of
Cpc
objects.- Raises
- class zhmcclient.Cpc(manager, uri, name=None, properties=None)[source]
Representation of a managed CPC.
Derived from
BaseResource
; see there for common methods and attributes.Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case,
CpcManager
).Attributes:
Access to the LPARs in this CPC.
Access to the Partitions in this CPC.
Access to the Adapters in this CPC.
Access to the Virtual Switches in this CPC.
Access to the Capacity Groups in this CPC.
Access to the Virtual Switches in this CPC.
Access to the Reset Activation Profiles in this CPC.
Access to the Image Activation Profiles in this CPC.
Access to the Load Activation Profiles in this CPC.
Indicates whether this CPC is currently in DPM mode (Dynamic Partition Manager mode).
The maximum number of active logical partitions or partitions of this CPC.
full_properties
A boolean indicating whether or not the resource properties in this object are the full set of resource properties.
manager
Subclass of
BaseManager
: Manager object for this resource (and for all resources of the same type in the scope of that manager).name
The name of the resource.
properties
The properties of this resource that are currently present in this Python object, as a dictionary.
properties_timestamp
The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).
uri
The canonical URI path of the resource.
Methods:
feature_enabled
(feature_name)Indicates whether the specified feature is enabled for this CPC.
Returns information about the features available for this CPC.
update_properties
(properties)Update writeable properties of this CPC.
start
([wait_for_completion, operation_timeout])Start this CPC, using the HMC operation "Start CPC".
stop
([wait_for_completion, operation_timeout])Stop this CPC, using the HMC operation "Stop CPC".
import_profiles
(profile_area[, ...])Import activation profiles and/or system activity profiles for this CPC from the SE hard drive into the CPC using the HMC operation "Import Profiles".
export_profiles
(profile_area[, ...])Export activation profiles and/or system activity profiles from this CPC to the SE hard drive using the HMC operation "Export Profiles".
get_wwpns
(partitions)Return the WWPNs of the host ports (of the HBAs) of the specified Partitions of this CPC.
get_free_crypto_domains
([crypto_adapters])Return a list of crypto domains that are free for usage on a list of crypto adapters in this CPC.
set_power_save
(power_saving[, ...])Set the power save setting of this CPC.
set_power_capping
(power_capping_state[, ...])Set the power capping settings of this CPC.
Return the energy management properties of the CPC.
Return the storage groups that are associated to this CPC.
validate_lun_path
(host_wwpn, host_port, ...)Validate if an FCP storage volume on an actual storage subsystem is reachable from this CPC, through a specified host port and using a specified host WWPN.
add_temporary_capacity
(record_id[, ...])Add temporary processors to the CPC or increase temporary model capacity of the CPC.
remove_temporary_capacity
(record_id[, ...])Remove temporary processors from the CPC or decrease temporary model capacity of the CPC.
set_auto_start_list
(auto_start_list)Set the auto-start list of partitions for this CPC.
import_dpm_configuration
(dpm_configuration)Import a DPM configuration into this CPC.
Export a DPM configuration from this CPC and return it.
__repr__
()Return a string with the state of this resource, for debug purposes.
__str__
()Return a human readable string representation of this resource.
auto_update_enabled
()Return whether auto-update is currently enabled for the resource object.
disable_auto_update
()Disable auto-update for this resource object, if currently enabled.
enable_auto_update
()Enable auto-update for this resource object, if currently disabled.
get_properties_local
(names[, defaults])Return the values of a set of resource properties, using default values for those that are not present in this Python object, without retrieving them from the HMC.
get_property
(name)Return the value of a resource property.
prop
(name[, default])Return the value of a resource property, applying a default if it does not exist.
pull_full_properties
()Retrieve the full set of resource properties and cache them in this object.
update_properties_local
(properties)Update the values of a set of resource properties on this Python object without propagating the updates the HMC.
- property partitions
Access to the Partitions in this CPC.
- Type
- property virtual_switches
Access to the Virtual Switches in this CPC.
- Type
- property capacity_groups
Access to the Capacity Groups in this CPC.
- Type
- property vswitches
Access to the Virtual Switches in this CPC.
Deprecated: This attribute is deprecated and using it will cause a
exceptions.DeprecationWarning
to be issued. Usevirtual_switches
instead.- Type
- property reset_activation_profiles
Access to the Reset Activation Profiles in this CPC.
- property image_activation_profiles
Access to the Image Activation Profiles in this CPC.
- property load_activation_profiles
Access to the Load Activation Profiles in this CPC.
- property dpm_enabled
Indicates whether this CPC is currently in DPM mode (Dynamic Partition Manager mode).
If the CPC is not currently in DPM mode, or if the CPC does not support DPM mode (i.e. before z13), False is returned.
Authorization requirements:
Object-access permission to this CPC.
- Raises
- Type
- property maximum_active_partitions
The maximum number of active logical partitions or partitions of this CPC.
The following table shows the maximum number of active logical partitions or partitions by machine generations supported at the HMC API:
Machine generation
Maximum partitions
z196
60
z114
30
zEC12
60
zBC12
30
z13 / Emperor
85
z13s / Rockhopper
40
z14 / Emperor II
85
z14-ZR1 / -LR1
40
z15-T01 / -LT1 / -GT2
85
z15-T02 / -LT2
40
- Raises
ValueError – Unknown machine type
- Type
Integer
- feature_enabled(feature_name)[source]
Indicates whether the specified feature is enabled for this CPC.
The HMC must generally support features, and the specified feature must be available for the CPC.
For a list of available features, see section “Features” in the HMC API, or use the
feature_info()
method.Authorization requirements:
Object-access permission to this CPC.
- Parameters
feature_name (string) – The name of the feature.
- Returns
True if the feature is enabled, or False if the feature is disabled (but available).
- Return type
- Raises
ValueError – Features are not supported on the HMC.
ValueError – The specified feature is not available for the CPC.
- feature_info()[source]
Returns information about the features available for this CPC.
Authorization requirements:
Object-access permission to this CPC.
- Returns
An iterable where each item represents one feature that is available for this CPC.
Each item is a dictionary with the following items:
name (unicode string): Name of the feature.
description (unicode string): Short description of the feature.
state (bool): Enablement state of the feature (True if the enabled, False if disabled).
- Return type
- Raises
ValueError – Features are not supported on the HMC.
- update_properties(properties)[source]
Update writeable properties of this CPC.
This method serializes with other methods that access or change properties on the same Python object.
Authorization requirements:
Object-access permission to this CPC.
Task permission for the “CPC Details” task.
- start(wait_for_completion=True, operation_timeout=None)[source]
Start this CPC, using the HMC operation “Start CPC”.
Authorization requirements:
Object-access permission to this CPC.
Task permission for the “Start (start a single DPM system)” task.
- Parameters
wait_for_completion (bool) –
Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows:
If True, this method will wait for completion of the asynchronous job performing the operation.
If False, this method will return immediately once the HMC has accepted the request to perform the operation.
operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a
OperationTimeout
is raised.
- Returns
If wait_for_completion is True, returns None.
If wait_for_completion is False, returns a
Job
object representing the asynchronously executing job on the HMC.- Return type
None or
Job
- Raises
OperationTimeout – The timeout expired while waiting for completion of the operation.
- stop(wait_for_completion=True, operation_timeout=None)[source]
Stop this CPC, using the HMC operation “Stop CPC”.
Authorization requirements:
Object-access permission to this CPC.
Task permission for the “Stop (stop a single DPM system)” task.
- Parameters
wait_for_completion (bool) –
Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows:
If True, this method will wait for completion of the asynchronous job performing the operation.
If False, this method will return immediately once the HMC has accepted the request to perform the operation.
operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a
OperationTimeout
is raised.
- Returns
If wait_for_completion is True, returns None.
If wait_for_completion is False, returns a
Job
object representing the asynchronously executing job on the HMC.- Return type
None or
Job
- Raises
OperationTimeout – The timeout expired while waiting for completion of the operation.
- import_profiles(profile_area, wait_for_completion=True, operation_timeout=None)[source]
Import activation profiles and/or system activity profiles for this CPC from the SE hard drive into the CPC using the HMC operation “Import Profiles”.
This operation is not permitted when the CPC is in DPM mode.
Authorization requirements:
Object-access permission to this CPC.
Task permission for the “CIM Actions ExportSettingsData” task.
- Parameters
profile_area (int) – The numbered hard drive area (1-4) from which the profiles are imported.
wait_for_completion (bool) –
Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows:
If True, this method will wait for completion of the asynchronous job performing the operation.
If False, this method will return immediately once the HMC has accepted the request to perform the operation.
operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a
OperationTimeout
is raised.
- Returns
If wait_for_completion is True, returns None.
If wait_for_completion is False, returns a
Job
object representing the asynchronously executing job on the HMC.- Return type
None or
Job
- Raises
OperationTimeout – The timeout expired while waiting for completion of the operation.
- export_profiles(profile_area, wait_for_completion=True, operation_timeout=None)[source]
Export activation profiles and/or system activity profiles from this CPC to the SE hard drive using the HMC operation “Export Profiles”.
This operation is not permitted when the CPC is in DPM mode.
Authorization requirements:
Object-access permission to this CPC.
Task permission for the “CIM Actions ExportSettingsData” task.
- Parameters
profile_area (int) – The numbered hard drive area (1-4) to which the profiles are exported. Any existing data is overwritten.
wait_for_completion (bool) –
Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows:
If True, this method will wait for completion of the asynchronous job performing the operation.
If False, this method will return immediately once the HMC has accepted the request to perform the operation.
operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a
OperationTimeout
is raised.
- Returns
If wait_for_completion is True, returns None.
If wait_for_completion is False, returns a
Job
object representing the asynchronously executing job on the HMC.- Return type
None or
Job
- Raises
OperationTimeout – The timeout expired while waiting for completion of the operation.
- get_wwpns(partitions)[source]
Return the WWPNs of the host ports (of the HBAs) of the specified Partitions of this CPC.
This method performs the HMC operation “Export WWPN List”.
Authorization requirements:
Object-access permission to this CPC.
Object-access permission to the Partitions designated by the “partitions” parameter.
Task permission for the “Export WWPNs” task.
- Parameters
partitions (iterable of
Partition
) – Partitions to be used.- Returns
A list of items for each WWPN, where each item is a dict with the following keys:
’partition-name’ (string): Name of the Partition.
’adapter-id’ (string): ID of the FCP Adapter.
’device-number’ (string): Virtual device number of the HBA.
’wwpn’ (string): WWPN of the HBA.
- Raises
- get_free_crypto_domains(crypto_adapters=None)[source]
Return a list of crypto domains that are free for usage on a list of crypto adapters in this CPC.
A crypto domain is considered free for usage if it is not assigned to any defined partition of this CPC in access mode ‘control-usage’ on any of the specified crypto adapters.
For this test, all currently defined partitions of this CPC are checked, regardless of whether or not they are active. This ensures that a crypto domain that is found to be free for usage can be assigned to a partition for ‘control-usage’ access to the specified crypto adapters, without causing a crypto domain conflict when activating that partition.
Note that a similar notion of free domains does not exist for access mode ‘control’, because a crypto domain on a crypto adapter can be in control access by multiple active partitions.
This method requires the CPC to be in DPM mode.
Example:
crypto domains adapters 0 1 2 3 +---+---+---+---+ c1 |A,c|a,c| | C | +---+---+---+---+ c2 |b,c|B,c| B | C | +---+---+---+---+
In this example, the CPC has two crypto adapters c1 and c2. For simplicity of the example, we assume these crypto adapters support only 4 crypto domains.
Partition A uses only adapter c1 and has domain 0 in ‘control-usage’ access (indicated by an upper case letter ‘A’ in the corresponding cell) and has domain 1 in ‘control’ access (indicated by a lower case letter ‘a’ in the corresponding cell).
Partition B uses only adapter c2 and has domain 0 in ‘control’ access and domains 1 and 2 in ‘control-usage’ access.
Partition C uses both adapters, and has domains 0 and 1 in ‘control’ access and domain 3 in ‘control-usage’ access.
The domains free for usage in this example are shown in the following table, for each combination of crypto adapters to be investigated:
crypto_adapters
domains free for usage
c1
1, 2
c2
0
c1, c2
(empty list)
Experimental: This method has been added in v0.14.0 and is currently considered experimental. Its interface may change incompatibly. Once the interface remains stable, this experimental marker will be removed.
Authorization requirements:
Object-access permission to this CPC.
Object-access permission to all of its Partitions.
Object-access permission to all of its crypto Adapters.
- Parameters
crypto_adapters (iterable of
Adapter
) –The crypto Adapters to be investigated.
None means to investigate all crypto adapters of this CPC.
- Returns
A sorted list of domain index numbers (integers) of the crypto domains that are free for usage on the specified crypto adapters.
Returns None, if
crypto_adapters
was an empty list or ifcrypto_adapters
was None and the CPC has no crypto adapters.- Raises
- set_power_save(power_saving, wait_for_completion=True, operation_timeout=None)[source]
Set the power save setting of this CPC.
The current power save setting in effect for a CPC is described in the “cpc-power-saving” property of the CPC.
This method performs the HMC operation “Set CPC Power Save”. It requires that the feature “Automate/advanced management suite” (FC 0020) is installed and enabled, and fails otherwise.
This method will also fail if the CPC is under group control.
Whether a CPC currently allows this method is described in the “cpc-power-save-allowed” property of the CPC.
Authorization requirements:
Object-access permission to this CPC.
Task permission for the “Power Save” task.
- Parameters
power_saving (string) –
The new power save setting, with the possible values:
”high-performance” - The power consumption and performance of the CPC are not reduced. This is the default setting.
”low-power” - Low power consumption for all components of the CPC enabled for power saving.
”custom” - Components may have their own settings changed individually. No component settings are actually changed when this mode is entered.
wait_for_completion (bool) –
Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows:
If True, this method will wait for completion of the asynchronous job performing the operation.
If False, this method will return immediately once the HMC has accepted the request to perform the operation.
operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a
OperationTimeout
is raised.
- Returns
If wait_for_completion is True, returns None.
If wait_for_completion is False, returns a
Job
object representing the asynchronously executing job on the HMC.- Return type
None or
Job
- Raises
HTTPError – See the HTTP status and reason codes of operation “Set CPC Power Save” in the HMC API book.
OperationTimeout – The timeout expired while waiting for completion of the operation.
- set_power_capping(power_capping_state, power_cap=None, wait_for_completion=True, operation_timeout=None)[source]
Set the power capping settings of this CPC. The power capping settings of a CPC define whether or not the power consumption of the CPC is limited and if so, what the limit is. Use this method to limit the peak power consumption of a CPC, or to remove a power consumption limit for a CPC.
The current power capping settings in effect for a CPC are described in the “cpc-power-capping-state” and “cpc-power-cap-current” properties of the CPC.
This method performs the HMC operation “Set CPC Power Capping”. It requires that the feature “Automate/advanced management suite” (FC 0020) is installed and enabled, and fails otherwise.
This method will also fail if the CPC is under group control.
Whether a CPC currently allows this method is described in the “cpc-power-cap-allowed” property of the CPC.
Authorization requirements:
Object-access permission to this CPC.
Task permission for the “Power Capping” task.
- Parameters
power_capping_state (string) –
The power capping state to be set, with the possible values:
”disabled” - The power cap of the CPC is not set and the peak power consumption is not limited. This is the default setting.
”enabled” - The peak power consumption of the CPC is limited to the specified power cap value.
”custom” - Individually configure the components for power capping. No component settings are actually changed when this mode is entered.
power_cap (integer) –
The power cap value to be set, as a power consumption in Watt. This parameter is required not to be None if power_capping_state=”enabled”.
The specified value must be between the values of the CPC properties “cpc-power-cap-minimum” and “cpc-power-cap-maximum”.
wait_for_completion (bool) –
Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows:
If True, this method will wait for completion of the asynchronous job performing the operation.
If False, this method will return immediately once the HMC has accepted the request to perform the operation.
operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a
OperationTimeout
is raised.
- Returns
If wait_for_completion is True, returns None.
If wait_for_completion is False, returns a
Job
object representing the asynchronously executing job on the HMC.- Return type
None or
Job
- Raises
HTTPError – See the HTTP status and reason codes of operation “Set CPC Power Save” in the HMC API book.
OperationTimeout – The timeout expired while waiting for completion of the operation.
- get_energy_management_properties()[source]
Return the energy management properties of the CPC.
The returned energy management properties are a subset of the properties of the CPC resource, and are also available as normal properties of the CPC resource. In so far, there is no new data provided by this method. However, because only a subset of the properties is returned, this method is faster than retrieving the complete set of CPC properties (e.g. via
pull_full_properties()
).This method performs the HMC operation “Get CPC Energy Management Data”, and returns only the energy management properties for this CPC from the operation result. Note that in non-ensemble mode of a CPC, the HMC operation result will only contain data for the CPC alone.
It requires that the feature “Automate/advanced management suite” (FC 0020) is installed and enabled, and returns empty values for most properties, otherwise.
Authorization requirements:
Object-access permission to this CPC.
- Returns
A dictionary of properties of the CPC that are related to energy management. For details, see section “Energy management related additional properties” in the data model for the CPC resource in the HMC API book.
- Return type
- Raises
HTTPError – See the HTTP status and reason codes of operation “Get CPC Energy Management Data” in the HMC API book.
ParseError – Also raised by this method when the JSON response could be parsed but contains inconsistent data.
- list_associated_storage_groups(full_properties=False, filter_args=None)[source]
Return the storage groups that are associated to this CPC.
If the CPC does not support the “dpm-storage-management” feature, or does not have it enabled, an empty list is returned.
Storage groups for which the authenticated user does not have object-access permission are not included.
Authorization requirements:
Object-access permission to any storage groups to be included in the result.
- Parameters
full_properties (bool) – Controls that the full set of resource properties for each returned storage group is being retrieved, vs. only the following short set: “object-uri”, “cpc-uri”, “name”, “fulfillment-state”, and “type”.
filter_args (dict) –
Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering.
None causes no filtering to happen.
The ‘cpc-uri’ property is automatically added to the filter arguments and must not be specified in this parameter.
- Returns
A list of
StorageGroup
objects.- Raises
ValueError – The filter_args parameter specifies the ‘cpc-uri’ property
- validate_lun_path(host_wwpn, host_port, wwpn, lun)[source]
Validate if an FCP storage volume on an actual storage subsystem is reachable from this CPC, through a specified host port and using a specified host WWPN.
This method performs the “Validate LUN Path” HMC operation.
If the volume is reachable, the method returns. If the volume is not reachable (and no other errors occur), an
HTTPError
is raised, and itsreason
property indicates the reason as follows:484: Target WWPN cannot be reached.
485: Target WWPN can be reached, but LUN cannot be reached.
The CPC must have the “dpm-storage-management” feature enabled.
- Parameters
host_wwpn (string) –
World wide port name (WWPN) of the host (CPC), as a hexadecimal number of up to 16 characters in any lexical case.
This may be the WWPN of the physical storage port, or a WWPN of a virtual HBA. In any case, it must be the kind of WWPN that is used for zoning and LUN masking in the SAN.
host_port (
Port
) – Storage port on the CPC that will be used for validating reachability.wwpn (string) – World wide port name (WWPN) of the FCP storage subsystem containing the storage volume, as a hexadecimal number of up to 16 characters in any lexical case.
lun (string) – Logical Unit Number (LUN) of the storage volume within its FCP storage subsystem, as a hexadecimal number of up to 16 characters in any lexical case.
Authorization requirements:
Object-access permission to the storage group owning this storage volume.
Task permission to the “Configure Storage - Storage Administrator” task.
- Raises
- add_temporary_capacity(record_id, software_model=None, processor_info=None, test=False, force=False)[source]
Add temporary processors to the CPC or increase temporary model capacity of the CPC.
This method performs the “Add Temporary Capacity” HMC operation.
If the request would exceed the processor capacity that is installed on the CPC or the limits of the capacity record, the operation will fail, unless the force parameter is True.
- Parameters
record_id (string) – The ID of the capacity record to be used for any updates of the processor capacity.
software_model (string) –
The name of the software model to be activated for the CPC. This must be one of the software models defined within the specified capacity record. The software model implies the number of general purpose processors that will be active once the operation succeeds.
If None, the software model and the number of general purpose processors of the CPC will remain unchanged.
processor_info (dict) –
The number of specialty processors to be added to the CPC.
If None, the number of specialty processors of the CPC will remain unchanged.
Each item in the dictionary identifies the number of one type of specialty processor. The key of the item must be a string specifying the type of specialty processor (‘aap’, ‘cbp’, ‘icf’, ‘ifl’, ‘iip’, ‘sap’), and the value of the item must be an integer specifying the number of processors of that type to be added.
If an item for a type of specialty processor is not provided, or if the value of the item is None, the number of specialty processors of that type will remain unchanged.
test (bool) – Indicates whether test (True) or real (False) resources should be activated. Test resources are automatically deactivated after 24h.
force (bool) – True indicates that the operation should proceed if not enough processors are available. True is permitted only for CBU, CPE and loaner capacity records.
Authorization requirements:
Object-access permission to the CPC.
Task permission to the “Perform Model Conversion” task.
- Raises
- remove_temporary_capacity(record_id, software_model=None, processor_info=None)[source]
Remove temporary processors from the CPC or decrease temporary model capacity of the CPC.
This method performs the “Remove Temporary Capacity” HMC operation.
You can only remove activated resources for the specific offering. You cannot remove dedicated engines or the last processor of a processor type. If you remove resources back to the base configuration, the capacity record activation is completed. That is, if you remove the last temporary processor, your capacity record is deactivated. For a CBU and On/Off CoD record, to add resources again, you must use another
add_temporary_capacity()
operation. For an On/Off CoD test or CPE record, once the record is deactivated, it is no longer available for use. You can then delete the record.After removal of the resources, the capacity record remains as an installed record. If you want a record deleted, you must manually delete the record on the “Installed Records” page in the HMC GUI.
- Parameters
record_id (string) – The ID of the capacity record to be used for any updates of the processor capacity.
software_model (string) –
The name of the software model to be activated for the CPC. This must be one of the software models defined within the specified capacity record. The software model implies the number of general purpose processors that will be active once the operation succeeds.
If None, the software model and the number of general purpose processors of the CPC will remain unchanged.
processor_info (dict) –
The number of specialty processors to be removed from the CPC.
If None, the number of specialty processors of the CPC will remain unchanged.
Each item in the dictionary identifies the number of one type of specialty processor. The key of the item must be a string specifying the type of specialty processor (‘aap’, ‘cbp’, ‘icf’, ‘ifl’, ‘iip’, ‘sap’), and the value of the item must be an integer specifying the number of processors of that type to be removed.
If an item for a type of specialty processor is not provided, or if the value of the item is None, the number of specialty processors of that type will remain unchanged.
Authorization requirements:
Object-access permission to the CPC.
Task permission to the “Perform Model Conversion” task.
- Raises
- set_auto_start_list(auto_start_list)[source]
Set the auto-start list of partitions for this CPC.
The current auto-start list is replaced with this new list.
The auto-start list may contain named partition groups that are formed just for the purpose of auto-starting (they have nothing to do with Group objects on the HMC).
This method performs the “Set Auto-Start List” HMC operation.
This method requires the CPC to be in DPM mode.
- Parameters
auto_start_list (list) –
The auto-start list to be set.
Each list item is one of:
tuple(partition, post_start_delay)
tuple(partition_list, name, description, post_start_delay)
Where:
partition (
Partition
): The partition to be auto-started.post_start_delay (int): Delay in seconds to wait after starting this partition or partition group, and before the next partition or partition group in the list is started.
partition_list (list of
Partition
): The partitions in the partition group to be auto-started.name (string): Name of the partition group.
description (string): Description of the partition group.
Authorization requirements:
Object-access permission to this CPC.
Task permission to the “System Details” task.
Object-access permission to all partitions specified in the auto-start list.
- Raises
- import_dpm_configuration(dpm_configuration)[source]
Import a DPM configuration into this CPC.
This includes settable CPC properties, settable properties of physical adapters, Hipersocket adapters, partitions with their child objects, virtual functions, virtual switches, capacity groups, storage related resources, storage ports, and network ports.
This method performs the “Import DPM Configuration” HMC operation.
This method requires the CPC to be in DPM mode.
Authorization requirements:
Object-access permission to this CPC.
Task permission to the “Import Dynamic Partition Manager Configuration” task.
- Parameters
dpm_configuration (dict) –
A DPM configuration, represented as a dictionary with the fields described for the “Import DPM Configuration” operation in the HMC API book.
Resource URIs are represented as URI strings in the fields of the DPM configuration, as described for the request body fields of the HMC operation. URIs of imported resource objects can be chosen to be preserved or newly allocated via the “preserve-uris” field.
Adapter PCHIDs may be different between the imported adapter objects and the actual adapters in this CPC and can be mapped via the “adapter-mapping” field.
Host WWPNs of FICON adapters can be chosen to be preserved or newly allocated via the “preserve-wwpns” field.
- Returns
If the complete input DPM configuration has been applied to the CPC, None is returned.
If only a part of the input DPM configuration has been applied, a list of dict objects is returned that describe what was not applied. For details, see the description of the response of the “Import DPM Configuration” operation in the HMC API book.
To verify that the complete input DPM configuration has been applied, the caller must verify the return value to be None and not just verify that no exceptions have been raised.
- Return type
- Raises
- export_dpm_configuration()[source]
Export a DPM configuration from this CPC and return it.
The DPM configuration includes settable CPC properties and all DPM specific objects of or associated with the CPC, such as adapters with their ports, virtual switches, partitions with their child objects, capacity groups, and various storage and tape related resources.
Note that all adapters of the CPC are exported, even when they are not used by partitions.
This method performs the “Get Inventory” HMC operation and extracts all information into the result.
This method requires the CPC to be in DPM mode.
Authorization requirements:
Object-access permission to this CPC.
- Returns
A DPM configuration, represented as a dictionary with the fields described for the “Import DPM Configuration” operation in the HMC API book.
Resource URIs are represented as URI strings in the fields of the DPM configuration, as described for the request body fields of the HMC operation.
The optional “preserve-uris”, “preserve-wwpns”, and “adapter-mapping” fields will not be in the returned dictionary, so their defaults will be used when importing this DPM configuration unchanged to a CPC.
The returned DPM configuration object can be passed to
import_dpm_configuration()
either unchanged, or after changing it, e.g. by adding the optional “preserve-uris”, “preserve-wwpns”, or “adapter-mapping” fields.- Return type
- Raises
ConsistencyError –
Unmanaged CPCs
A CPC (Central Processor Complex) is a physical IBM Z or LinuxONE computer.
A particular HMC can manage multiple CPCs and can discover other CPCs that are not managed by that HMC. Such other CPCs are called “unmanaged CPCs” and they may or may not be managed by another HMC.
This section describes the interface for unmanaged CPCs using resource class
UnmanagedCpc
and the corresponding manager class
UnmanagedCpcManager
.
- class zhmcclient.UnmanagedCpcManager(console)[source]
Manager providing access to the CPCs that have been discovered by the HMC this client is connected to, but are not managed by it. They may or may not be managed by another HMC.
Derived from
BaseManager
; see there for common methods and attributes.Objects of this class are not directly created by the user; they are accessible via the following instance variable of a
Console
object:Attributes:
Console defining the scope for this manager.
class_name
The resource class name
parent
Subclass of
BaseResource
: Parent resource defining the scope for this manager.resource_class
The Python class of the parent resource of this manager.
session
Session
: Session with the HMC.Methods:
list
([full_properties, filter_args])List the unmanaged CPCs exposed by the HMC this client is connected to.
__repr__
()Return a string with the state of this manager object, for debug purposes.
find
(**filter_args)Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g.
find_by_name
(name)Find a resource by name (i.e.
find_local
(name, uri[, properties])Return a local resource object without fetching it from the HMC.
findall
(**filter_args)Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g.
flush
()Invalidate the Name-URI cache of this manager.
invalidate_cache
()Invalidate the Name-URI cache of this manager.
resource_object
(uri_or_oid[, props])Return a minimalistic Python resource object for this resource class, that is scoped to this manager.
- list(full_properties=False, filter_args=None)[source]
List the unmanaged CPCs exposed by the HMC this client is connected to.
Because the CPCs are unmanaged, the returned
UnmanagedCpc
objects cannot perform any operations and will have only the following properties:object-uri
name
Authorization requirements:
None
- Parameters
full_properties (bool) – Ignored (exists for consistency with other list() methods).
filter_args (dict) –
Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering.
None causes no filtering to happen, i.e. all resources are returned.
- Returns
A list of
UnmanagedCpc
objects.- Raises
- class zhmcclient.UnmanagedCpc(manager, uri, name=None, properties=None)[source]
Representation of an unmanaged CPC.
Derived from
BaseResource
; see there for common methods and attributes.Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case,
UnmanagedCpcManager
).Methods:
__repr__
()Return a string with the state of this resource, for debug purposes.
__str__
()Return a human readable string representation of this resource.
auto_update_enabled
()Return whether auto-update is currently enabled for the resource object.
disable_auto_update
()Disable auto-update for this resource object, if currently enabled.
enable_auto_update
()Enable auto-update for this resource object, if currently disabled.
get_properties_local
(names[, defaults])Return the values of a set of resource properties, using default values for those that are not present in this Python object, without retrieving them from the HMC.
get_property
(name)Return the value of a resource property.
prop
(name[, default])Return the value of a resource property, applying a default if it does not exist.
pull_full_properties
()Retrieve the full set of resource properties and cache them in this object.
update_properties_local
(properties)Update the values of a set of resource properties on this Python object without propagating the updates the HMC.
Attributes:
full_properties
A boolean indicating whether or not the resource properties in this object are the full set of resource properties.
manager
Subclass of
BaseManager
: Manager object for this resource (and for all resources of the same type in the scope of that manager).name
The name of the resource.
properties
The properties of this resource that are currently present in this Python object, as a dictionary.
properties_timestamp
The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).
uri
The canonical URI path of the resource.
Activation profiles
An Activation Profile controls the activation of a CPC or LPAR. They are used to tailor the operation of a CPC and are stored in the Support Element associated with the CPC.
Activation Profile resources are contained in CPC resources.
Activation Profile resources only exist in CPCs that are not in DPM mode.
- TODO: If Reset Activation Profiles are used to determine the CPC mode,
should they not exist in all CPC modes?
There are three types of Activation Profiles:
Reset: The Reset Activation Profile defines for a CPC the mode in which the CPC licensed internal code will be loaded (e.g. DPM mode or classic mode) and how much central storage and expanded storage will be used.
Image: For CPCs in classic mode, each LPAR can have an Image Activation Profile. The Image Activation Profile determines the number of CPs that the LPAR will use and whether these CPs will be dedicated to the LPAR or shared. It also allows assigning the amount of central storage and expanded storage that will be used by each LPAR.
Load: For CPCs in classic mode, each LPAR can have a Load Activation Profile. The Load Activation Profile defines the channel address of the device that the operating system for that LPAR will be loaded (booted) from.
- class zhmcclient.ActivationProfileManager(cpc, profile_type)[source]
Manager providing access to the Activation Profiles of a particular type in a particular CPC (the scoping CPC).
Possible types of activation profiles are:
Reset Activation Profile
Image Activation Profile
Load Activation Profile
Derived from
BaseManager
; see there for common methods and attributes.Objects of this class are not directly created by the user; they are accessible via the following instance variables of a
Cpc
object (in classic mode or ensemble mode):Attributes:
CPC defining the scope for this manager.
Type of the Activation Profiles managed by this object:
class_name
The resource class name
parent
Subclass of
BaseResource
: Parent resource defining the scope for this manager.resource_class
The Python class of the parent resource of this manager.
session
Session
: Session with the HMC.Methods:
list
([full_properties, filter_args])List the Activation Profiles of this CPC, of the profile type managed by this object.
__repr__
()Return a string with the state of this manager object, for debug purposes.
find
(**filter_args)Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g.
find_by_name
(name)Find a resource by name (i.e.
find_local
(name, uri[, properties])Return a local resource object without fetching it from the HMC.
findall
(**filter_args)Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g.
flush
()Invalidate the Name-URI cache of this manager.
invalidate_cache
()Invalidate the Name-URI cache of this manager.
resource_object
(uri_or_oid[, props])Return a minimalistic Python resource object for this resource class, that is scoped to this manager.
- property profile_type
Type of the Activation Profiles managed by this object:
'reset'
- Reset Activation Profiles'image'
- Image Activation Profiles'load'
- Load Activation Profiles
- Type
- list(full_properties=False, filter_args=None)[source]
List the Activation Profiles of this CPC, of the profile type managed by this object.
Authorization requirements:
Object-access permission to this CPC.
- Parameters
full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation.
filter_args (dict) –
Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering.
None causes no filtering to happen, i.e. all resources are returned.
- Returns
A list of
ActivationProfile
objects.- Raises
- class zhmcclient.ActivationProfile(manager, uri, name=None, properties=None)[source]
Representation of an Activation Profile of a particular type.
Derived from
BaseResource
; see there for common methods and attributes.Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case,
ActivationProfileManager
).Methods:
update_properties
(properties)Update writeable properties of this Activation Profile.
__repr__
()Return a string with the state of this resource, for debug purposes.
__str__
()Return a human readable string representation of this resource.
auto_update_enabled
()Return whether auto-update is currently enabled for the resource object.
disable_auto_update
()Disable auto-update for this resource object, if currently enabled.
enable_auto_update
()Enable auto-update for this resource object, if currently disabled.
get_properties_local
(names[, defaults])Return the values of a set of resource properties, using default values for those that are not present in this Python object, without retrieving them from the HMC.
get_property
(name)Return the value of a resource property.
prop
(name[, default])Return the value of a resource property, applying a default if it does not exist.
pull_full_properties
()Retrieve the full set of resource properties and cache them in this object.
update_properties_local
(properties)Update the values of a set of resource properties on this Python object without propagating the updates the HMC.
Attributes:
full_properties
A boolean indicating whether or not the resource properties in this object are the full set of resource properties.
manager
Subclass of
BaseManager
: Manager object for this resource (and for all resources of the same type in the scope of that manager).name
The name of the resource.
properties
The properties of this resource that are currently present in this Python object, as a dictionary.
properties_timestamp
The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).
uri
The canonical URI path of the resource.
- update_properties(properties)[source]
Update writeable properties of this Activation Profile.
This method serializes with other methods that access or change properties on the same Python object.
Authorization requirements:
Object-access permission to the CPC of this Activation Profile.
Task permission for the “Customize/Delete Activation Profiles” task.
- Parameters
properties (dict) – New values for the properties to be updated. Properties not to be updated are omitted. Allowable properties are the properties with qualifier (w) in section ‘Data model’ in section ‘<profile_type> activation profile’ in the HMC API book, where <profile_type> is the profile type of this object (e.g. Reset, Load, Image).
- Raises
LPARs
A LPAR (Logical Partition) is a subset of the hardware resources of a CPC in classic mode (or ensemble mode), virtualized as a separate computer.
LPARs cannot be created or deleted by the user; they can only be listed.
LPAR resources are contained in CPC resources.
LPAR resources only exist in CPCs that are in classic mode (or ensemble mode). CPCs in DPM mode have Partition resources, instead.
- class zhmcclient.LparManager(cpc)[source]
Manager providing access to the LPARs in a particular CPC.
Derived from
BaseManager
; see there for common methods and attributes.Objects of this class are not directly created by the user; they are accessible via the following instance variable of a
Cpc
object (in DPM mode):Attributes:
CPC defining the scope for this manager.
class_name
The resource class name
parent
Subclass of
BaseResource
: Parent resource defining the scope for this manager.resource_class
The Python class of the parent resource of this manager.
session
Session
: Session with the HMC.Methods:
list
([full_properties, filter_args])List the LPARs in this CPC.
__repr__
()Return a string with the state of this manager object, for debug purposes.
find
(**filter_args)Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g.
find_by_name
(name)Find a resource by name (i.e.
find_local
(name, uri[, properties])Return a local resource object without fetching it from the HMC.
findall
(**filter_args)Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g.
flush
()Invalidate the Name-URI cache of this manager.
invalidate_cache
()Invalidate the Name-URI cache of this manager.
resource_object
(uri_or_oid[, props])Return a minimalistic Python resource object for this resource class, that is scoped to this manager.
- list(full_properties=False, filter_args=None)[source]
List the LPARs in this CPC.
Authorization requirements:
Object-access permission to this CPC.
Object-access permission to any LPAR to be included in the result.
- Parameters
full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation.
filter_args (dict) –
Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering.
None causes no filtering to happen, i.e. all resources are returned.
- Returns
A list of
Lpar
objects.- Raises
- class zhmcclient.Lpar(manager, uri, name=None, properties=None)[source]
Representation of an LPAR.
Derived from
BaseResource
; see there for common methods and attributes.Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case,
LparManager
).Methods:
update_properties
(properties)Update writeable properties of this LPAR.
activate
([wait_for_completion, ...])Activate (start) this LPAR, using the HMC operation "Activate Logical Partition".
deactivate
([wait_for_completion, ...])De-activate (stop) this LPAR, using the HMC operation "Deactivate Logical Partition".
scsi_load
(load_address, wwpn, lun[, ...])Load (boot) this LPAR from a designated SCSI device, using the HMC operation "SCSI Load".
scsi_dump
(load_address, wwpn, lun[, ...])Load a standalone dump program from a designated SCSI device in this LPAR, using the HMC operation "SCSI Dump".
load
([load_address, load_parameter, ...])Load (boot) this LPAR from a load address (boot device), using the HMC operation "Load Logical Partition".
stop
([wait_for_completion, ...])Stop this LPAR, using the HMC operation "Stop Logical Partition".
reset_clear
([force, wait_for_completion, ...])Initialize this LPAR by clearing its pending interruptions, resetting its channel subsystem, and resetting its processors, using the HMC operation "Reset Clear".
open_os_message_channel
([...])Open a JMS message channel to this LPAR's operating system, returning the string "topic" representing the message channel.
send_os_command
(os_command_text[, is_priority])Send a command to the operating system running in this LPAR.
psw_restart
([wait_for_completion, ...])Restart this LPAR, using the HMC operation "PSW Restart".
wait_for_status
(status[, status_timeout])Wait until the status of this LPAR has a desired value.
__repr__
()Return a string with the state of this resource, for debug purposes.
__str__
()Return a human readable string representation of this resource.
auto_update_enabled
()Return whether auto-update is currently enabled for the resource object.
disable_auto_update
()Disable auto-update for this resource object, if currently enabled.
enable_auto_update
()Enable auto-update for this resource object, if currently disabled.
get_properties_local
(names[, defaults])Return the values of a set of resource properties, using default values for those that are not present in this Python object, without retrieving them from the HMC.
get_property
(name)Return the value of a resource property.
prop
(name[, default])Return the value of a resource property, applying a default if it does not exist.
pull_full_properties
()Retrieve the full set of resource properties and cache them in this object.
update_properties_local
(properties)Update the values of a set of resource properties on this Python object without propagating the updates the HMC.
Attributes:
full_properties
A boolean indicating whether or not the resource properties in this object are the full set of resource properties.
manager
Subclass of
BaseManager
: Manager object for this resource (and for all resources of the same type in the scope of that manager).name
The name of the resource.
properties
The properties of this resource that are currently present in this Python object, as a dictionary.
properties_timestamp
The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).
uri
The canonical URI path of the resource.
- update_properties(properties)[source]
Update writeable properties of this LPAR.
This method serializes with other methods that access or change properties on the same Python object.
Authorization requirements:
Object-access permission to this LPAR.
Before HMC API version 3.6 in an update to HMC 2.15.0: Object-access permission to the CPC of this LPAR.
Task permission for the “Change Object Definition” task.
Since HMC 2.14.1: If the “next-activation-profile-name” property is to be updated, task permission for the “Change Object Options” task or the “Customize/Delete Activation Profiles” task.
Before HMC 2.15.0: For an LPAR whose activation-mode is “zaware”, task permission for the “Firmware Details” task.
Since HMC 2.15.0: If any of the “ssc-” or “zaware-” properties is to be updated, task permission for the “Firmware Details” task.
Since HMC 2.15.0: If any of the numbers of allocated or reserved cores is to be updated, task permission for the “Logical Processor Add” task.
- activate(wait_for_completion=True, operation_timeout=None, status_timeout=None, allow_status_exceptions=False, activation_profile_name=None, force=False)[source]
Activate (start) this LPAR, using the HMC operation “Activate Logical Partition”.
This HMC operation has deferred status behavior: If the asynchronous job on the HMC is complete, it takes a few seconds until the LPAR status has reached the desired value. If wait_for_completion=True, this method repeatedly checks the status of the LPAR after the HMC operation has completed, and waits until the status is in the desired state “not-operating” (which indicates that the LPAR is active but no operating system is running), or “operating”, or if allow_status_exceptions was set additionally in the state “exceptions”.
Authorization requirements:
Object-access permission to this LPAR.
Before HMC API version 3.6 in an update to HMC 2.15.0: Object-access permission to the CPC of this LPAR.
Task permission for the “Activate” task.
- Parameters
wait_for_completion (bool) –
Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows:
If True, this method will wait for completion of the asynchronous job performing the operation, and for the status becoming “not-operating” or “operating” (or in addition “exceptions”, if allow_status_exceptions was set.
If False, this method will return immediately once the HMC has accepted the request to perform the operation.
operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a
OperationTimeout
is raised.status_timeout (number) – Timeout in seconds, for waiting that the status of the LPAR has reached the desired status, after the HMC operation has completed. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a
StatusTimeout
is raised.allow_status_exceptions (bool) – Boolean controlling whether LPAR status “exceptions” is considered an additional acceptable end status when wait_for_completion is set.
activation_profile_name (string) –
Name of the image
ActivationProfile
to use for activation.None means that the activation profile specified in the next-activation-profile-name property of the LPAR is used.
force (bool) –
Boolean controlling whether this operation is permitted when the LPAR is in the “operating” status.
TBD: What will happen with the LPAR in that case (deactivated then activated? nothing?)
- Returns
If wait_for_completion is True, returns None.
If wait_for_completion is False, returns a
Job
object representing the asynchronously executing job on the HMC.- Return type
None or
Job
- Raises
OperationTimeout – The timeout expired while waiting for completion of the operation.
StatusTimeout – The timeout expired while waiting for the desired LPAR status.
- deactivate(wait_for_completion=True, operation_timeout=None, status_timeout=None, allow_status_exceptions=False, force=False)[source]
De-activate (stop) this LPAR, using the HMC operation “Deactivate Logical Partition”.
This HMC operation has deferred status behavior: If the asynchronous job on the HMC is complete, it takes a few seconds until the LPAR status has reached the desired value. If wait_for_completion=True, this method repeatedly checks the status of the LPAR after the HMC operation has completed, and waits until the status is in the desired state “not-activated”, or if allow_status_exceptions was set additionally in the state “exceptions”.
Authorization requirements:
Object-access permission to this LPAR.
Before HMC API version 3.6 in an update to HMC 2.15.0: Object-access permission to the CPC of this LPAR.
Task permission for the “Deactivate” task.
- Parameters
wait_for_completion (bool) –
Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows:
If True, this method will wait for completion of the asynchronous job performing the operation, and for the status becoming “non-activated” (or in addition “exceptions”, if allow_status_exceptions was set.
If False, this method will return immediately once the HMC has accepted the request to perform the operation.
operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a
OperationTimeout
is raised.status_timeout (number) – Timeout in seconds, for waiting that the status of the LPAR has reached the desired status, after the HMC operation has completed. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a
StatusTimeout
is raised.allow_status_exceptions (bool) – Boolean controlling whether LPAR status “exceptions” is considered an additional acceptable end status when wait_for_completion is set.
force (bool) –
Boolean controlling whether this operation is permitted when the LPAR is in the “operating” status.
TBD: What will happen with the LPAR in that case (deactivated then activated? nothing?)
- Returns
If wait_for_completion is True, returns None.
If wait_for_completion is False, returns a
Job
object representing the asynchronously executing job on the HMC.- Return type
None or
Job
- Raises
OperationTimeout – The timeout expired while waiting for completion of the operation.
StatusTimeout – The timeout expired while waiting for the desired LPAR status.
- scsi_load(load_address, wwpn, lun, load_parameter=None, disk_partition_id=None, operating_system_specific_load_parameters=None, boot_record_logical_block_address=None, force=False, wait_for_completion=True, operation_timeout=None, status_timeout=None, allow_status_exceptions=False, secure_boot=False)[source]
Load (boot) this LPAR from a designated SCSI device, using the HMC operation “SCSI Load”.
This HMC operation has deferred status behavior: If the asynchronous job on the HMC is complete, it takes a few seconds until the LPAR status has reached the desired value. If wait_for_completion=True, this method repeatedly checks the status of the LPAR after the HMC operation has completed, and waits until the status is in the desired state “operating”, or if allow_status_exceptions was set additionally in the state “exceptions”.
Authorization requirements:
Object-access permission to this LPAR.
Before HMC API version 3.6 in an update to HMC 2.15.0: Object-access permission to the CPC of this LPAR.
Task permission for the “SCSI Load” task.
- Parameters
load_address (string) – Device number of the boot device.
wwpn (string) – Worldwide port name (WWPN) of the target SCSI device to be used for this operation, in hexadecimal.
lun (string) – Hexadecimal logical unit number (LUN) to be used for the SCSI Load.
load_parameter (string) – Optional load control string. If empty string or None, it is not passed to the HMC.
disk_partition_id (integer) – Optional disk-partition-id (also called the boot program selector) to be used for the SCSI Load. If None, it is not passed to the HMC.
operating_system_specific_load_parameters (string) – Optional operating system specific load parameters to be used for the SCSI Load.
boot_record_logical_block_address (string) – Optional hexadecimal boot record logical block address to be used for the SCSI Load.
force (bool) – Boolean controlling whether this operation is permitted when the LPAR is in the “operating” status.
wait_for_completion (bool) –
Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows:
If True, this method will wait for completion of the asynchronous job performing the operation, and for the status becoming “operating” (or in addition “exceptions”, if allow_status_exceptions was set.
If False, this method will return immediately once the HMC has accepted the request to perform the operation.
operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a
OperationTimeout
is raised.status_timeout (number) – Timeout in seconds, for waiting that the status of the LPAR has reached the desired status, after the HMC operation has completed. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a
StatusTimeout
is raised.allow_status_exceptions (bool) – Boolean controlling whether LPAR status “exceptions” is considered an additional acceptable end status when wait_for_completion is set.
secure_boot (bool) – Bollean controlling whether the system checks the software signature of what is loaded against what the distributor signed it with. Requires z15 or later.
- Returns
If wait_for_completion is True, returns None.
If wait_for_completion is False, returns a
Job
object representing the asynchronously executing job on the HMC.- Return type
None or
Job
- Raises
OperationTimeout – The timeout expired while waiting for completion of the operation.
StatusTimeout – The timeout expired while waiting for the desired LPAR status.
- scsi_dump(load_address, wwpn, lun, load_parameter=None, disk_partition_id=None, operating_system_specific_load_parameters=None, boot_record_logical_block_address=None, os_ipl_token=None, wait_for_completion=True, operation_timeout=None, status_timeout=None, allow_status_exceptions=False, force=False)[source]
Load a standalone dump program from a designated SCSI device in this LPAR, using the HMC operation “SCSI Dump”.
This HMC operation has deferred status behavior: If the asynchronous job on the HMC is complete, it takes a few seconds until the LPAR status has reached the desired value. If wait_for_completion=True, this method repeatedly checks the status of the LPAR after the HMC operation has completed, and waits until the status is in the desired state “operating”, or if allow_status_exceptions was set additionally in the state “exceptions”.
Authorization requirements:
Object-access permission to this LPAR.
Before HMC API version 3.6 in an update to HMC 2.15.0: Object-access permission to the CPC of this LPAR.
Task permission for the “SCSI Dump” task.
- Parameters
load_address (string) – Device number of the boot device.
wwpn (string) – Worldwide port name (WWPN) of the target SCSI device to be used for this operation, in hexadecimal.
lun (string) – Hexadecimal logical unit number (LUN) to be used for the SCSI Load.
load_parameter (string) – Optional load control string. If empty string or None, it is not passed to the HMC.
disk_partition_id (integer) – Optional disk-partition-id (also called the boot program selector) to be used for the SCSI Load. If None, it is not passed to the HMC.
operating_system_specific_load_parameters (string) – Optional operating system specific load parameters to be used for the SCSI Load.
boot_record_logical_block_address (string) – Optional hexadecimal boot record logical block address to be used for the SCSI Load.
os_ipl_token (string) – Optional hexadecimal value to be used for the SCSI dump.
wait_for_completion (bool) –
Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows:
If True, this method will wait for completion of the asynchronous job performing the operation, and for the status becoming “operating” (or in addition “exceptions”, if allow_status_exceptions was set.
If False, this method will return immediately once the HMC has accepted the request to perform the operation.
operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a
OperationTimeout
is raised.status_timeout (number) – Timeout in seconds, for waiting that the status of the LPAR has reached the desired status, after the HMC operation has completed. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a
StatusTimeout
is raised.allow_status_exceptions (bool) – Boolean controlling whether LPAR status “exceptions” is considered an additional acceptable end status when wait_for_completion is set.
force (bool) – Boolean controlling whether this operation is permitted when the LPAR is in the “operating” status.
- Returns
If wait_for_completion is True, returns None.
If wait_for_completion is False, returns a
Job
object representing the asynchronously executing job on the HMC.- Return type
None or
Job
- Raises
OperationTimeout – The timeout expired while waiting for completion of the operation.
StatusTimeout – The timeout expired while waiting for the desired LPAR status.
- load(load_address=None, load_parameter=None, clear_indicator=True, store_status_indicator=False, wait_for_completion=True, operation_timeout=None, status_timeout=None, allow_status_exceptions=False, force=False)[source]
Load (boot) this LPAR from a load address (boot device), using the HMC operation “Load Logical Partition”.
This HMC operation has deferred status behavior: If the asynchronous job on the HMC is complete, it takes a few seconds until the LPAR status has reached the desired value. If wait_for_completion=True, this method repeatedly checks the status of the LPAR after the HMC operation has completed, and waits until the status is in the desired state “operating”, or if allow_status_exceptions was set additionally in the state “exceptions”.
Authorization requirements:
Object-access permission to this LPAR.
Before HMC API version 3.6 in an update to HMC 2.15.0: Object-access permission to the CPC of this LPAR.
Task permission for the “Load” task.
- Parameters
load_address (string) – Device number of the boot device. Up to z13, this parameter is required. Starting with z14, this parameter is optional and defaults to the load address specified in the ‘last-used-load-address’ property of the Lpar.
load_parameter (string) – Optional load control string. If empty string or None, it is not passed to the HMC.
clear_indicator (bool) – Optional boolean controlling whether the memory should be cleared before performing the load or not cleared. The default value is True.
store_status_indicator (bool) – Optional boolean controlling whether the status should be stored before performing the Load. The default value is False.
wait_for_completion (bool) –
Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows:
If True, this method will wait for completion of the asynchronous job performing the operation, and for the status becoming “operating” (or in addition “exceptions”, if allow_status_exceptions was set.
If False, this method will return immediately once the HMC has accepted the request to perform the operation.
operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a
OperationTimeout
is raised.status_timeout (number) – Timeout in seconds, for waiting that the status of the LPAR has reached the desired status, after the HMC operation has completed. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a
StatusTimeout
is raised.allow_status_exceptions (bool) – Boolean controlling whether LPAR status “exceptions” is considered an additional acceptable end status when wait_for_completion is set.
force (bool) –
Boolean controlling whether this operation is permitted when the LPAR is in the “operating” status.
TBD: What will happen with the LPAR in that case (deactivated then activated? nothing?)
- Returns
If wait_for_completion is True, returns None.
If wait_for_completion is False, returns a
Job
object representing the asynchronously executing job on the HMC.- Return type
None or
Job
- Raises
OperationTimeout – The timeout expired while waiting for completion of the operation.
StatusTimeout – The timeout expired while waiting for the desired LPAR status.
- stop(wait_for_completion=True, operation_timeout=None, status_timeout=None, allow_status_exceptions=False)[source]
Stop this LPAR, using the HMC operation “Stop Logical Partition”. The stop operation stops the processors from processing instructions.
This HMC operation has deferred status behavior: If the asynchronous job on the HMC is complete, it takes a few seconds until the LPAR status has reached the desired value. If wait_for_completion=True, this method repeatedly checks the status of the LPAR after the HMC operation has completed, and waits until the status is in the desired state “not-operating”, or if allow_status_exceptions was set additionally in the state “exceptions”.
Authorization requirements:
Object-access permission to this LPAR.
Before HMC API version 3.6 in an update to HMC 2.15.0: Object-access permission to the CPC of this LPAR.
Task permission for the “Stop” task.
- Parameters
wait_for_completion (bool) –
Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows:
If True, this method will wait for completion of the asynchronous job performing the operation, and for the status becoming “not-operating” (or in addition “exceptions”, if allow_status_exceptions was set.
If False, this method will return immediately once the HMC has accepted the request to perform the operation.
operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a
OperationTimeout
is raised.status_timeout (number) – Timeout in seconds, for waiting that the status of the LPAR has reached the desired status, after the HMC operation has completed. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a
StatusTimeout
is raised.allow_status_exceptions (bool) – Boolean controlling whether LPAR status “exceptions” is considered an additional acceptable end status when wait_for_completion is set.
- Returns
If wait_for_completion is True, returns None.
If wait_for_completion is False, returns a
Job
object representing the asynchronously executing job on the HMC.- Return type
None or
Job
- Raises
OperationTimeout – The timeout expired while waiting for completion of the operation.
StatusTimeout – The timeout expired while waiting for the desired LPAR status.
- reset_clear(force=False, wait_for_completion=True, operation_timeout=None, status_timeout=None, allow_status_exceptions=False)[source]
Initialize this LPAR by clearing its pending interruptions, resetting its channel subsystem, and resetting its processors, using the HMC operation “Reset Clear”.
This HMC operation has deferred status behavior: If the asynchronous job on the HMC is complete, it takes a few seconds until the LPAR status has reached the desired value. If wait_for_completion=True, this method repeatedly checks the status of the LPAR after the HMC operation has completed, and waits until the status is in the desired state “operating”, or if allow_status_exceptions was set additionally in the state “exceptions”.
Authorization requirements:
Object-access permission to this LPAR.
Before HMC API version 3.6 in an update to HMC 2.15.0: Object-access permission to the CPC of this LPAR.
Task permission for the “Reset Clear” task.
- Parameters
force (bool) – Boolean controlling whether this operation is permitted when the LPAR is in the “operating” status. The default is False.
wait_for_completion (bool) –
Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows:
If True, this method will wait for completion of the asynchronous job performing the operation, and for the status becoming “operating” (or in addition “exceptions”, if allow_status_exceptions was set.
If False, this method will return immediately once the HMC has accepted the request to perform the operation.
operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a
OperationTimeout
is raised.status_timeout (number) – Timeout in seconds, for waiting that the status of the LPAR has reached the desired status, after the HMC operation has completed. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a
StatusTimeout
is raised.allow_status_exceptions (bool) – Boolean controlling whether LPAR status “exceptions” is considered an additional acceptable end status when wait_for_completion is set.
- Returns
If wait_for_completion is True, returns None.
If wait_for_completion is False, returns a
Job
object representing the asynchronously executing job on the HMC.- Return type
None or
Job
- Raises
OperationTimeout – The timeout expired while waiting for completion of the operation.
StatusTimeout – The timeout expired while waiting for the desired LPAR status.
- open_os_message_channel(include_refresh_messages=True)[source]
Open a JMS message channel to this LPAR’s operating system, returning the string “topic” representing the message channel.
Authorization requirements:
Object-access permission to this Partition.
Task permission to the “Operating System Messages” task at least in view-only mode.
- Parameters
include_refresh_messages (bool) –
Boolean controlling whether refresh operating systems messages should be sent, as follows:
If True, refresh messages will be recieved when the user connects to the topic. The default.
If False, refresh messages will not be recieved when the user connects to the topic.
- Returns
Returns a string representing the os-message-notification JMS topic. The user can connect to this topic to start the flow of operating system messages.
- Return type
- Raises
- send_os_command(os_command_text, is_priority=False)[source]
Send a command to the operating system running in this LPAR.
Authorization requirements:
Object-access permission to this Partition.
Task permission to the “Operating System Messages” task in modification mode.
- Parameters
os_command_text (string) – The text of the operating system command.
is_priority (bool) –
Boolean controlling whether this is a priority operating system command, as follows:
If True, this message is treated as a priority operating system command.
If False, this message is not treated as a priority operating system command. The default.
- Returns
None
- Raises
- psw_restart(wait_for_completion=True, operation_timeout=None, status_timeout=None, allow_status_exceptions=False)[source]
Restart this LPAR, using the HMC operation “PSW Restart”.
This HMC operation has deferred status behavior: If the asynchronous job on the HMC is complete, it takes a few seconds until the LPAR status has reached the desired value. If wait_for_completion=True, this method repeatedly checks the status of the LPAR after the HMC operation has completed, and waits until the status is in the desired state “operating”, or if allow_status_exceptions was set additionally in the state “exceptions”.
Authorization requirements:
Object-access permission to this LPAR.
Before HMC API version 3.6 in an update to HMC 2.15.0: Object-access permission to the CPC of this LPAR.
Task permission for the “PSW Restart” task.
- Parameters
wait_for_completion (bool) –
Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows:
If True, this method will wait for completion of the asynchronous job performing the operation, and for the status becoming “operating” (or in addition “exceptions”, if allow_status_exceptions was set.
If False, this method will return immediately once the HMC has accepted the request to perform the operation.
operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a
OperationTimeout
is raised.status_timeout (number) – Timeout in seconds, for waiting that the status of the LPAR has reached the desired status, after the HMC operation has completed. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a
StatusTimeout
is raised.allow_status_exceptions (bool) – Boolean controlling whether LPAR status “exceptions” is considered an additional acceptable end status when wait_for_completion is set.
- Returns
If wait_for_completion is True, returns None.
If wait_for_completion is False, returns a
Job
object representing the asynchronously executing job on the HMC.- Return type
None or
Job
- Raises
OperationTimeout – The timeout expired while waiting for completion of the operation.
StatusTimeout – The timeout expired while waiting for the desired LPAR status.
- wait_for_status(status, status_timeout=None)[source]
Wait until the status of this LPAR has a desired value.
- Parameters
status (string or iterable of string) –
Desired LPAR status or set of status values to reach; one or more of the following values:
"not-activated"
- The LPAR is not active."not-operating"
- The LPAR is active but no operating system is running in the LPAR."operating"
- The LPAR is active and an operating system is running in the LPAR."exceptions"
- The LPAR or its CPC has one or more unusual conditions.
Note that the description of LPAR status values in the HMC API book (as of its version 2.13.1) is partly confusing.
status_timeout (number) – Timeout in seconds, for waiting that the status of the LPAR has reached one of the desired status values. The special value 0 means that no timeout is set. None means that the default status timeout will be used. If the timeout expires , a
StatusTimeout
is raised.
- Raises
StatusTimeout – The timeout expired while waiting for the desired LPAR status.
Partitions
A Partition is a subset of the hardware resources of a CPC in DPM mode, virtualized as a separate computer.
Partitions can be created and deleted dynamically, and their resources such as CPU, memory or I/O devices can be configured dynamically. You can create as many partition definitions as you want, but only a specific number of partitions can be active at any given time.
TODO: How can a user find out what the maximum is, before it is reached?
Partition resources are contained in CPC resources.
Partition resources only exist in CPCs that are in DPM mode. CPCs in classic mode (or ensemble mode) have LPAR resources, instead.
- class zhmcclient.PartitionManager(cpc)[source]
Manager providing access to the Partitions in a particular CPC.
Derived from
BaseManager
; see there for common methods and attributes.Objects of this class are not directly created by the user; they are accessible via the following instance variable of a
Cpc
object (in DPM mode):Attributes:
CPC defining the scope for this manager.
class_name
The resource class name
parent
Subclass of
BaseResource
: Parent resource defining the scope for this manager.resource_class
The Python class of the parent resource of this manager.
session
Session
: Session with the HMC.Methods:
list
([full_properties, filter_args])List the Partitions in this CPC.
create
(properties)Create and configure a Partition in this CPC.
__repr__
()Return a string with the state of this manager object, for debug purposes.
find
(**filter_args)Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g.
find_by_name
(name)Find a resource by name (i.e.
find_local
(name, uri[, properties])Return a local resource object without fetching it from the HMC.
findall
(**filter_args)Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g.
flush
()Invalidate the Name-URI cache of this manager.
invalidate_cache
()Invalidate the Name-URI cache of this manager.
resource_object
(uri_or_oid[, props])Return a minimalistic Python resource object for this resource class, that is scoped to this manager.
- list(full_properties=False, filter_args=None)[source]
List the Partitions in this CPC.
Authorization requirements:
Object-access permission to this CPC.
Object-access permission to any Partition to be included in the result.
- Parameters
full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation.
filter_args (dict) –
Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering.
None causes no filtering to happen, i.e. all resources are returned.
- Returns
A list of
Partition
objects.- Raises
- create(properties)[source]
Create and configure a Partition in this CPC.
Authorization requirements:
Object-access permission to this CPC.
Task permission to the “New Partition” task.
- Parameters
properties (dict) – Initial property values. Allowable properties are defined in section ‘Request body contents’ in section ‘Create Partition’ in the HMC API book.
- Returns
The resource object for the new Partition. The object will have its ‘object-uri’ property set as returned by the HMC, and will also have the input properties set.
- Return type
- Raises
- class zhmcclient.Partition(manager, uri, name=None, properties=None)[source]
Representation of a Partition.
Derived from
BaseResource
; see there for common methods and attributes.Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case,
PartitionManager
).Attributes:
Access to the NICs in this Partition.
Access to the HBAs in this Partition.
Access to the Virtual Functions in this Partition.
full_properties
A boolean indicating whether or not the resource properties in this object are the full set of resource properties.
manager
Subclass of
BaseManager
: Manager object for this resource (and for all resources of the same type in the scope of that manager).name
The name of the resource.
properties
The properties of this resource that are currently present in this Python object, as a dictionary.
properties_timestamp
The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).
uri
The canonical URI path of the resource.
Methods:
feature_enabled
(feature_name)Indicates whether the specified feature is enabled for the CPC of this partition.
Returns information about the features available for the CPC of this partition.
start
([wait_for_completion, ...])Start (activate) this Partition, using the HMC operation "Start Partition".
stop
([wait_for_completion, ...])Stop (deactivate) this Partition, using the HMC operation "Stop Partition".
delete
()Delete this Partition.
update_properties
(properties)Update writeable properties of this Partition.
dump_partition
(parameters[, ...])Dump this Partition, by loading a standalone dump program from a SCSI device and starting its execution, using the HMC operation 'Dump Partition'.
start_dump_program
(parameters[, ...])Dump this Partition, by loading a standalone dump program from a storage volume and starting its execution, using the HMC operation 'Start Dump Program'.
psw_restart
([wait_for_completion, ...])Initiates a PSW restart for this Partition, using the HMC operation 'Perform PSW Restart'.
mount_iso_image
(image, image_name, ins_file_name)Upload an ISO image and associate it to this Partition using the HMC operation 'Mount ISO Image'.
Unmount the currently mounted ISO from this Partition using the HMC operation 'Unmount ISO Image'.
open_os_message_channel
([...])Open a JMS message channel to this partition's operating system, returning the string "topic" representing the message channel.
send_os_command
(os_command_text[, is_priority])Send a command to the operating system running in this partition.
wait_for_status
(status[, status_timeout])Wait until the status of this partition has a desired value.
increase_crypto_config
(crypto_adapters, ...)Add crypto adapters and/or crypto domains to the crypto configuration of this partition.
decrease_crypto_config
(crypto_adapters, ...)Remove crypto adapters and/or crypto domains from the crypto configuration of this partition.
Change the access mode for a crypto domain that is currently included in the crypto configuration of this partition.
zeroize_crypto_domain
(crypto_adapter, ...)Zeroize a single crypto domain on a crypto adapter.
attach_storage_group
(storage_group)Attach a storage group to this partition.
detach_storage_group
(storage_group)Detach a storage group from this partition.
list_attached_storage_groups
([full_properties])Return the storage groups that are attached to this partition.
__repr__
()Return a string with the state of this resource, for debug purposes.
__str__
()Return a human readable string representation of this resource.
auto_update_enabled
()Return whether auto-update is currently enabled for the resource object.
disable_auto_update
()Disable auto-update for this resource object, if currently enabled.
enable_auto_update
()Enable auto-update for this resource object, if currently disabled.
get_properties_local
(names[, defaults])Return the values of a set of resource properties, using default values for those that are not present in this Python object, without retrieving them from the HMC.
get_property
(name)Return the value of a resource property.
prop
(name[, default])Return the value of a resource property, applying a default if it does not exist.
pull_full_properties
()Retrieve the full set of resource properties and cache them in this object.
update_properties_local
(properties)Update the values of a set of resource properties on this Python object without propagating the updates the HMC.
- property hbas
Access to the HBAs in this Partition.
If the “dpm-storage-management” feature is enabled, this property is None.
- Type
- property virtual_functions
Access to the Virtual Functions in this Partition.
- feature_enabled(feature_name)[source]
Indicates whether the specified feature is enabled for the CPC of this partition.
The HMC must generally support features, and the specified feature must be available for the CPC.
For a list of available features, see section “Features” in the HMC API, or use the
feature_info()
method.Authorization requirements:
Object-access permission to this partition.
- Parameters
feature_name (string) – The name of the feature.
- Returns
True if the feature is enabled, or False if the feature is disabled (but available).
- Return type
- Raises
ValueError – Features are not supported on the HMC.
ValueError – The specified feature is not available for the CPC.
- feature_info()[source]
Returns information about the features available for the CPC of this partition.
Authorization requirements:
Object-access permission to this partition.
- Returns
An iterable where each item represents one feature that is available for the CPC of this partition.
Each item is a dictionary with the following items:
name (unicode string): Name of the feature.
description (unicode string): Short description of the feature.
state (bool): Enablement state of the feature (True if the enabled, False if disabled).
- Return type
- Raises
ValueError – Features are not supported on the HMC.
- start(wait_for_completion=True, operation_timeout=None, status_timeout=None)[source]
Start (activate) this Partition, using the HMC operation “Start Partition”.
This HMC operation has deferred status behavior: If the asynchronous job on the HMC is complete, it takes a few seconds until the partition status has reached the desired value (it still may show status “paused”). If wait_for_completion=True, this method repeatedly checks the status of the partition after the HMC operation has completed, and waits until the status is in one of the desired states “active” or “degraded”.
TODO: Describe what happens if the maximum number of active partitions is exceeded.
Authorization requirements:
Object-access permission to this Partition.
Task permission to the “Start Partition” task.
- Parameters
wait_for_completion (bool) –
Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows:
If True, this method will wait for completion of the asynchronous job performing the operation.
If False, this method will return immediately once the HMC has accepted the request to perform the operation.
operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a
OperationTimeout
is raised.status_timeout (number) – Timeout in seconds, for waiting that the status of the partition has reached the desired status, after the HMC operation has completed. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a
StatusTimeout
is raised.
- Returns
If wait_for_completion is True, returns an empty
dict
object.If wait_for_completion is False, returns a
Job
object representing the asynchronously executing job on the HMC.- Return type
- Raises
OperationTimeout – The timeout expired while waiting for completion of the operation.
StatusTimeout – The timeout expired while waiting for the desired partition status.
- stop(wait_for_completion=True, operation_timeout=None, status_timeout=None)[source]
Stop (deactivate) this Partition, using the HMC operation “Stop Partition”.
Authorization requirements:
Object-access permission to this Partition.
Task permission to the “Stop Partition” task.
- Parameters
wait_for_completion (bool) –
Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows:
If True, this method will wait for completion of the asynchronous job performing the operation.
If False, this method will return immediately once the HMC has accepted the request to perform the operation.
operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a
OperationTimeout
is raised.status_timeout (number) – Timeout in seconds, for waiting that the status of the partition has reached the desired status, after the HMC operation has completed. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a
StatusTimeout
is raised.
- Returns
If wait_for_completion is True, returns an empty
dict
object.If wait_for_completion is False, returns a
Job
object representing the asynchronously executing job on the HMC.- Return type
- Raises
OperationTimeout – The timeout expired while waiting for completion of the operation.
StatusTimeout – The timeout expired while waiting for the desired partition status.
- delete()[source]
Delete this Partition.
Authorization requirements:
Object-access permission to this Partition.
Task permission to the “Delete Partition” task.
- Raises
- update_properties(properties)[source]
Update writeable properties of this Partition.
This method serializes with other methods that access or change properties on the same Python object.
Authorization requirements:
Object-access permission to this Partition.
Task permission to the “Partition Details” task.
- dump_partition(parameters, wait_for_completion=True, operation_timeout=None)[source]
Dump this Partition, by loading a standalone dump program from a SCSI device and starting its execution, using the HMC operation ‘Dump Partition’.
This operation requires that the CPC does not have the storage management feature (i.e. is a z13).
Authorization requirements:
Object-access permission to this Partition.
Task permission to the “Dump Partition” task.
- Parameters
parameters (dict) – Input parameters for the operation. Allowable input parameters are defined in section ‘Request body contents’ in section ‘Dump Partition’ in the HMC API book.
wait_for_completion (bool) –
Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows:
If True, this method will wait for completion of the asynchronous job performing the operation.
If False, this method will return immediately once the HMC has accepted the request to perform the operation.
operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a
OperationTimeout
is raised.
- Returns
If wait_for_completion is True, returns an empty
dict
object.If wait_for_completion is False, returns a
Job
object representing the asynchronously executing job on the HMC.- Return type
- Raises
OperationTimeout – The timeout expired while waiting for completion of the operation.
- start_dump_program(parameters, wait_for_completion=True, operation_timeout=None)[source]
Dump this Partition, by loading a standalone dump program from a storage volume and starting its execution, using the HMC operation ‘Start Dump Program’.
This operation requires that the CPC has the storage management feature (i.e. is a z14 or later).
Authorization requirements:
Object-access permission to this Partition.
Task permission to the “Dump Partition” task.
- Parameters
parameters (dict) – Input parameters for the operation. Allowable input parameters are defined in section ‘Request body contents’ in section ‘Start Dump Program’ in the HMC API book.
wait_for_completion (bool) –
Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows:
If True, this method will wait for completion of the asynchronous job performing the operation.
If False, this method will return immediately once the HMC has accepted the request to perform the operation.
operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a
OperationTimeout
is raised.
- Returns
If wait_for_completion is True, returns an empty
dict
object.If wait_for_completion is False, returns a
Job
object representing the asynchronously executing job on the HMC.- Return type
- Raises
OperationTimeout – The timeout expired while waiting for completion of the operation.
- psw_restart(wait_for_completion=True, operation_timeout=None)[source]
Initiates a PSW restart for this Partition, using the HMC operation ‘Perform PSW Restart’.
Authorization requirements:
Object-access permission to this Partition.
Task permission to the “PSW Restart” task.
- Parameters
wait_for_completion (bool) –
Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows:
If True, this method will wait for completion of the asynchronous job performing the operation.
If False, this method will return immediately once the HMC has accepted the request to perform the operation.
operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a
OperationTimeout
is raised.
- Returns
If wait_for_completion is True, returns an empty
dict
object.If wait_for_completion is False, returns a
Job
object representing the asynchronously executing job on the HMC.- Return type
- Raises
OperationTimeout – The timeout expired while waiting for completion of the operation.
- mount_iso_image(image, image_name, ins_file_name)[source]
Upload an ISO image and associate it to this Partition using the HMC operation ‘Mount ISO Image’.
When the partition already has an ISO image associated, the newly uploaded image replaces the current one.
Authorization requirements:
Object-access permission to this Partition.
Task permission to the “Partition Details” task.
- Parameters
image (byte string or file-like object) –
The content of the ISO image.
Images larger than 2GB cannot be specified as a Byte string; they must be specified as a file-like object.
File-like objects must have opened the file in binary mode.
image_name (string) –
The displayable name of the image.
This value must be a valid Linux file name without directories, must not contain blanks, and must end with ‘.iso’ in lower case.
This value will be shown in the ‘boot-iso-image-name’ property of this partition.
ins_file_name (string) –
The path name of the INS file within the file system of the ISO image.
This value will be shown in the ‘boot-iso-ins-file’ property of this partition.
- Raises
- unmount_iso_image()[source]
Unmount the currently mounted ISO from this Partition using the HMC operation ‘Unmount ISO Image’. This operation sets the partition’s ‘boot-iso-image-name’ and ‘boot-iso-ins-file’ properties to null.
Authorization requirements:
Object-access permission to this Partition.
Task permission to the “Partition Details” task.
- Raises
- open_os_message_channel(include_refresh_messages=True)[source]
Open a JMS message channel to this partition’s operating system, returning the string “topic” representing the message channel.
Authorization requirements:
Object-access permission to this Partition.
Task permission to the “Operating System Messages” task at least in view-only mode.
- Parameters
include_refresh_messages (bool) –
Boolean controlling whether refresh operating systems messages should be sent, as follows:
If True, refresh messages will be recieved when the user connects to the topic. The default.
If False, refresh messages will not be recieved when the user connects to the topic.
- Returns
Returns a string representing the os-message-notification JMS topic. The user can connect to this topic to start the flow of operating system messages.
- Return type
- Raises
- send_os_command(os_command_text, is_priority=False)[source]
Send a command to the operating system running in this partition.
Authorization requirements:
Object-access permission to this Partition.
Task permission to the “Operating System Messages” task in modification mode.
- Parameters
os_command_text (string) – The text of the operating system command.
is_priority (bool) –
Boolean controlling whether this is a priority operating system command, as follows:
If True, this message is treated as a priority operating system command.
If False, this message is not treated as a priority operating system command. The default.
- Returns
None
- Raises
- wait_for_status(status, status_timeout=None)[source]
Wait until the status of this partition has a desired value.
- Parameters
status (string or iterable of string) – Desired partition status or set of status values to reach; one or more of the values defined for the ‘status’ property in the data model for partitions in the HMC API book.
status_timeout (number) – Timeout in seconds, for waiting that the status of the partition has reached one of the desired status values. The special value 0 means that no timeout is set. None means that the default status timeout will be used. If the timeout expires, a
StatusTimeout
is raised.
- Raises
StatusTimeout – The status timeout expired while waiting for the desired partition status.
- increase_crypto_config(crypto_adapters, crypto_domain_configurations)[source]
Add crypto adapters and/or crypto domains to the crypto configuration of this partition.
The general principle for maintaining crypto configurations of partitions is as follows: Each adapter included in the crypto configuration of a partition has all crypto domains included in the crypto configuration. Each crypto domain included in the crypto configuration has the same access mode on all adapters included in the crypto configuration.
Example: Assume that the current crypto configuration of a partition includes crypto adapter A and crypto domains 0 and 1. When this method is called to add adapter B and domain configurations for domains 1 and 2, the resulting crypto configuration of the partition will include domains 0, 1, and 2 on each of the adapters A and B.
Authorization requirements:
Object-access permission to this Partition.
Object-access permission to the specified Crypto Adapter.
Task permission to the “Partition Details” task.
- Parameters
crypto_adapters (iterable of
Adapter
) – Crypto adapters that should be added to the crypto configuration of this partition.crypto_domain_configurations (iterable of domain_config) –
Crypto domain configurations that should be added to the crypto configuration of this partition.
A crypto domain configuration (domain_config) is a dictionary with the following keys:
"domain-index"
(integer): Domain index of the crypto domain.The domain index is a number in the range of 0 to a maximum that depends on the model of the crypto adapter and the CPC model. For the Crypto Express 5S adapter in a z13, the maximum domain index is 84.
"access-mode"
(string): Access mode for the crypto domain.The access mode specifies the way the partition can use the crypto domain on the crypto adapter(s), using one of the following string values:
"control"
- The partition can load cryptographic keys into the domain, but it may not use the domain to perform cryptographic operations."control-usage"
- The partition can load cryptographic keys into the domain, and it can use the domain to perform cryptographic operations.
- Raises
- decrease_crypto_config(crypto_adapters, crypto_domain_indexes)[source]
Remove crypto adapters and/or crypto domains from the crypto configuration of this partition.
For the general principle for maintaining crypto configurations of partitions, see
increase_crypto_config()
.Example: Assume that the current crypto configuration of a partition includes crypto adapters A, B and C and crypto domains 0, 1, and 2 (on each of the adapters). When this method is called to remove adapter C and domain 2, the resulting crypto configuration of the partition will include domains 0 and 1 on each of the adapters A and B.
Authorization requirements:
Object-access permission to this Partition.
Object-access permission to the specified Crypto Adapters.
Task permission to the “Partition Details” task.
- Parameters
crypto_adapters (iterable of
Adapter
) – Crypto adapters that should be removed from the crypto configuration of this partition.crypto_domain_indexes (iterable of integer) – Domain indexes of the crypto domains that should be removed from the crypto configuration of this partition. For values, see
increase_crypto_config()
.
- Raises
- change_crypto_domain_config(crypto_domain_index, access_mode)[source]
Change the access mode for a crypto domain that is currently included in the crypto configuration of this partition.
The access mode will be changed for the specified crypto domain on all crypto adapters currently included in the crypto configuration of this partition.
For the general principle for maintaining crypto configurations of partitions, see
increase_crypto_config()
.Authorization requirements:
Object-access permission to this Partition.
Task permission to the “Partition Details” task.
- Parameters
crypto_domain_index (integer) – Domain index of the crypto domain to be changed. For values, see
increase_crypto_config()
.access_mode (string) – The new access mode for the crypto domain. For values, see
increase_crypto_config()
.
- Raises
- zeroize_crypto_domain(crypto_adapter, crypto_domain_index)[source]
Zeroize a single crypto domain on a crypto adapter.
Zeroizing a crypto domain clears the cryptographic keys and non-compliance mode settings in the crypto domain.
The crypto domain must be attached to this partition in “control-usage” access mode.
Supported CPC versions: z14 GA2 and above, and the corresponding LinuxOne systems.
Authorization requirements:
Object-access permission to this Partition.
Object-access permission to the specified Crypto Adapter.
Task permission to the “Zeroize Crypto Domain” task.
- Parameters
- Raises
- attach_storage_group(storage_group)[source]
Attach a storage group to this partition.
This will cause the storage volumes of the storage group to be attached to the partition, instantiating any necessary virtual storage resource objects.
A storage group can be attached to a partition regardless of its fulfillment state. The fulfillment state of its storage volumes and thus of the entire storage group changes as volumes are discovered by DPM, and will eventually reach “complete”.
The CPC must have the “dpm-storage-management” feature enabled.
Authorization requirements:
Object-access permission to this partition.
Object-access permission to the specified storage group.
Task permission to the “Partition Details” task.
- Parameters
storage_group (
StorageGroup
) – Storage group to be attached. The storage group must not currently be attached to this partition.- Raises
- detach_storage_group(storage_group)[source]
Detach a storage group from this partition.
This will cause the storage volumes of the storage group to be detached from the partition, removing any virtual storage resource objects that had been created upon attachment.
A storage group can be detached from a partition regardless of its fulfillment state. The fulfillment state of its storage volumes changes as volumes are discovered by DPM.
The CPC must have the “dpm-storage-management” feature enabled.
Authorization requirements:
Object-access permission to this partition.
Task permission to the “Partition Details” task.
- Parameters
storage_group (
StorageGroup
) – Storage group to be detached. The storage group must currently be attached to this partition.- Raises
- list_attached_storage_groups(full_properties=False)[source]
Return the storage groups that are attached to this partition.
The CPC must have the “dpm-storage-management” feature enabled.
Authorization requirements:
Object-access permission to this partition.
- Parameters
full_properties (bool) –
Controls that the full set of resource properties for each returned storage group is being retrieved, vs. only the following short set: “object-uri”, “object-id”, “class”, “parent”.
TODO: Verify short list of properties.
- Returns
List of
StorageGroup
objects representing the storage groups that are attached to this partition.- Raises
Adapters
An Adapter is a physical adapter card (e.g. OSA-Express adapter, Crypto adapter) or a logical adapter (e.g. HiperSockets switch).
Adapter resources are contained in CPC resources.
Adapters only exist in CPCs that are in DPM mode.
There are four types of Adapters:
Network Adapters: Network adapters enable communication through different networking transport protocols. These network adapters are OSA-Express, HiperSockets and RoCE-Express. DPM automatically discovers OSA-Express and RoCE-Express adapters because they are physical cards that are installed on the CPC. In contrast, HiperSockets are logical adapters and must be created and configured by an administrator using the ‘Create Hipersocket’ operation (see create_hipersocket()). Network Interface Cards (NICs) provide a partition with access to networks. Each NIC represents a unique connection between the partition and a specific network adapter.
Storage Adapters: Fibre Channel connections provide high-speed connections between CPCs and storage devices. DPM automatically discovers any storage adapters installed on the CPC. Host bus adapters (HBAs) provide a partition with access to external storage area networks (SANs) and devices that are connected to a CPC. Each HBA represents a unique connection between the partition and a specific storage adapter.
Accelerator Adapters: Accelerator adapters provide specialized functions to improve performance or use of computer resource like the IBM System z Enterprise Data Compression (zEDC) feature. DPM automatically discovers accelerators that are installed on the CPC. An accelerator virtual function provides a partition with access to zEDC features that are installed on a CPC. Each virtual function represents a unique connection between the partition and a physical feature card.
Crypto Adapters: Crypto adapters provide cryptographic processing functions. DPM automatically discovers cryptographic features that are installed on the CPC.
- class zhmcclient.AdapterManager(cpc)[source]
Manager providing access to the Adapters in a particular CPC.
Derived from
BaseManager
; see there for common methods and attributes.Objects of this class are not directly created by the user; they are accessible via the following instance variable of a
Cpc
object (in DPM mode):Attributes:
CPC defining the scope for this manager.
class_name
The resource class name
parent
Subclass of
BaseResource
: Parent resource defining the scope for this manager.resource_class
The Python class of the parent resource of this manager.
session
Session
: Session with the HMC.Methods:
list
([full_properties, filter_args])List the Adapters in this CPC.
create_hipersocket
(properties)Create and configure a HiperSockets Adapter in this CPC.
__repr__
()Return a string with the state of this manager object, for debug purposes.
find
(**filter_args)Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g.
find_by_name
(name)Find a resource by name (i.e.
find_local
(name, uri[, properties])Return a local resource object without fetching it from the HMC.
findall
(**filter_args)Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g.
flush
()Invalidate the Name-URI cache of this manager.
invalidate_cache
()Invalidate the Name-URI cache of this manager.
resource_object
(uri_or_oid[, props])Return a minimalistic Python resource object for this resource class, that is scoped to this manager.
- list(full_properties=False, filter_args=None)[source]
List the Adapters in this CPC.
Authorization requirements:
Object-access permission to this CPC.
Object-access permission to any Adapter to be included in the result.
- Parameters
full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation.
filter_args (dict) –
Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering.
None causes no filtering to happen, i.e. all resources are returned.
- Returns
A list of
Adapter
objects.- Raises
- create_hipersocket(properties)[source]
Create and configure a HiperSockets Adapter in this CPC.
Authorization requirements:
Object-access permission to the scoping CPC.
Task permission to the “Create HiperSockets Adapter” task.
- Parameters
properties (dict) – Initial property values. Allowable properties are defined in section ‘Request body contents’ in section ‘Create Hipersocket’ in the HMC API book.
- Returns
The resource object for the new HiperSockets Adapter. The object will have its ‘object-uri’ property set as returned by the HMC, and will also have the input properties set.
- Return type
- Raises
- class zhmcclient.Adapter(manager, uri, name=None, properties=None)[source]
Representation of an Adapter.
Derived from
BaseResource
; see there for common methods and attributes.For the properties of an Adapter, see section ‘Data model’ in section ‘Adapter object’ in the HMC API book.
Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case,
AdapterManager
).Attributes:
Access to the Ports of this Adapter.
Name of adapter property that specifies the adapter port URIs, or the empty string ('') for adapters without ports.
Adapter type specific URI segment for adapter port URIs, or the empty string ('') for adapters without ports.
The maximum number of crypto domains on this crypto adapter.
full_properties
A boolean indicating whether or not the resource properties in this object are the full set of resource properties.
manager
Subclass of
BaseManager
: Manager object for this resource (and for all resources of the same type in the scope of that manager).name
The name of the resource.
properties
The properties of this resource that are currently present in this Python object, as a dictionary.
properties_timestamp
The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).
uri
The canonical URI path of the resource.
Methods:
delete
()Delete this Adapter.
update_properties
(properties)Update writeable properties of this Adapter.
__repr__
()Return a string with the state of this Adapter, for debug purposes.
change_crypto_type
(crypto_type[, zeroize])Reconfigures a cryptographic adapter to a different crypto type.
change_adapter_type
(adapter_type)Reconfigures an adapter from one type to another, or to ungonfigured.
__str__
()Return a human readable string representation of this resource.
auto_update_enabled
()Return whether auto-update is currently enabled for the resource object.
disable_auto_update
()Disable auto-update for this resource object, if currently enabled.
enable_auto_update
()Enable auto-update for this resource object, if currently disabled.
get_properties_local
(names[, defaults])Return the values of a set of resource properties, using default values for those that are not present in this Python object, without retrieving them from the HMC.
get_property
(name)Return the value of a resource property.
prop
(name[, default])Return the value of a resource property, applying a default if it does not exist.
pull_full_properties
()Retrieve the full set of resource properties and cache them in this object.
update_properties_local
(properties)Update the values of a set of resource properties on this Python object without propagating the updates the HMC.
- property port_uris_prop
Name of adapter property that specifies the adapter port URIs, or the empty string (‘’) for adapters without ports.
For example, ‘network-port-uris’ for a network adapter.
- Type
- property port_uri_segment
Adapter type specific URI segment for adapter port URIs, or the empty string (‘’) for adapters without ports.
For example, ‘network-ports’ for a network adapter.
- Type
- property maximum_crypto_domains
The maximum number of crypto domains on this crypto adapter.
The following table shows the maximum number of crypto domains for crypto adapters supported on IBM Z machine generations in DPM mode. The corresponding LinuxONE machine generations are listed in the notes below the table:
Adapter type
Machine generations
Maximum domains
Crypto Express 5S
z14 (3) / z13 (1)
85
Crypto Express 5S
z14-ZR1 (4) / z13s (2)
40
Crypto Express 6S
z14 (3)
85
Crypto Express 6S
z14-ZR1 (4)
40
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
If this adapter is not a crypto adapter, None is returned.
If the crypto adapter card type is not known,
ValueError
is raised.- Raises
ValueError – Unknown crypto card type
- Type
Integer
- delete()[source]
Delete this Adapter.
The Adapter must be a HiperSockets Adapter.
Authorization requirements:
Object-access permission to the HiperSockets Adapter to be deleted.
Task permission to the “Delete HiperSockets Adapter” task.
- Raises
- update_properties(properties)[source]
Update writeable properties of this Adapter.
This method serializes with other methods that access or change properties on the same Python object.
Authorization requirements:
Object-access permission to the Adapter.
Task permission for the “Adapter Details” task.
- change_crypto_type(crypto_type, zeroize=None)[source]
Reconfigures a cryptographic adapter to a different crypto type. This operation is only supported for cryptographic adapters.
The cryptographic adapter must be varied offline before its crypto type can be reconfigured.
Authorization requirements:
Object-access permission to this Adapter.
Task permission to the “Adapter Details” task.
- Parameters
crypto_type (string) –
"accelerator"
: Crypto Express5S Accelerator"cca-coprocessor"
: Crypto Express5S CCA Coprocessor"ep11-coprocessor"
: Crypto Express5S EP11 Coprocessor
zeroize (bool) – Specifies whether the cryptographic adapter will be zeroized when it is reconfigured to a crypto type of
"accelerator"
. None means that the HMC-implemented default of True will be used.
- Raises
- change_adapter_type(adapter_type)[source]
Reconfigures an adapter from one type to another, or to ungonfigured. Currently, only storage adapters can be reconfigured, and their adapter type is the supported storage protocol (FCP vs. FICON).
Storage adapter instances (i.e.
Adapter
objects) represent daughter cards on a physical storage card. Current storage cards require both daughter cards to be configured to the same protocol, so changing the type of the targeted adapter will also change the type of the adapter instance that represents the other daughter card on the same physical card. Zhmcclient users that need to determine the related adapter instance can do so by finding the storage adapter with a matching first 9 characters (card ID and slot ID) of their card-location property values.The targeted adapter and its related adapter on the same storage card must not already have the desired adapter type, they must not be attached to any partition, and they must not have an adapter status of ‘exceptions’.
Authorization requirements:
Object-access permission to this Adapter.
Task permission to the “Configure Storage - System Programmer” task.
- Parameters
adapter_type (string) –
"fcp"
: FCP (Fibre Channel Protocol)"fc"
: FICON (Fibre Connection) protocol"not-configured"
: No adapter type configured
- Raises
Ports
A Port is a physical connector port (jack) of an Adapter.
Port resources are contained in Adapter resources.
Ports only exist in CPCs that are in DPM mode.
- class zhmcclient.PortManager(adapter, port_type)[source]
Manager providing access to the Ports of a particular Adapter.
Derived from
BaseManager
; see there for common methods and attributes.Objects of this class are not directly created by the user; they are accessible as properties in higher level resources (in this case, the
Adapter
object).Attributes:
Adapter defining the scope for this manager.
Type of the Ports managed by this object:
class_name
The resource class name
parent
Subclass of
BaseResource
: Parent resource defining the scope for this manager.resource_class
The Python class of the parent resource of this manager.
session
Session
: Session with the HMC.Methods:
list
([full_properties, filter_args])List the Ports of this Adapter.
__repr__
()Return a string with the state of this manager object, for debug purposes.
find
(**filter_args)Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g.
find_by_name
(name)Find a resource by name (i.e.
find_local
(name, uri[, properties])Return a local resource object without fetching it from the HMC.
findall
(**filter_args)Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g.
flush
()Invalidate the Name-URI cache of this manager.
invalidate_cache
()Invalidate the Name-URI cache of this manager.
resource_object
(uri_or_oid[, props])Return a minimalistic Python resource object for this resource class, that is scoped to this manager.
- property port_type
Type of the Ports managed by this object:
'network'
- Ports of a network adapter'storage'
- Ports of a storage adapterNone
- Adapter family without ports
- Type
- list(full_properties=False, filter_args=None)[source]
List the Ports of this Adapter.
If the adapter does not have any ports, an empty list is returned.
Authorization requirements:
Object-access permission to this Adapter.
- Parameters
full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation.
filter_args (dict) –
Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering.
None causes no filtering to happen, i.e. all resources are returned.
- Returns
A list of
Port
objects.- Raises
- class zhmcclient.Port(manager, uri, name=None, properties=None)[source]
Representation of a Port.
Derived from
BaseResource
; see there for common methods and attributes.For the properties of a Port, see section ‘Data model - Port Element Object’ in section ‘Adapter object’ in the HMC API book.
Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case,
PortManager
).Methods:
update_properties
(properties)Update writeable properties of this Port.
__repr__
()Return a string with the state of this resource, for debug purposes.
__str__
()Return a human readable string representation of this resource.
auto_update_enabled
()Return whether auto-update is currently enabled for the resource object.
disable_auto_update
()Disable auto-update for this resource object, if currently enabled.
enable_auto_update
()Enable auto-update for this resource object, if currently disabled.
get_properties_local
(names[, defaults])Return the values of a set of resource properties, using default values for those that are not present in this Python object, without retrieving them from the HMC.
get_property
(name)Return the value of a resource property.
prop
(name[, default])Return the value of a resource property, applying a default if it does not exist.
pull_full_properties
()Retrieve the full set of resource properties and cache them in this object.
update_properties_local
(properties)Update the values of a set of resource properties on this Python object without propagating the updates the HMC.
Attributes:
full_properties
A boolean indicating whether or not the resource properties in this object are the full set of resource properties.
manager
Subclass of
BaseManager
: Manager object for this resource (and for all resources of the same type in the scope of that manager).name
The name of the resource.
properties
The properties of this resource that are currently present in this Python object, as a dictionary.
properties_timestamp
The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).
uri
The canonical URI path of the resource.
- update_properties(properties)[source]
Update writeable properties of this Port.
This method serializes with other methods that access or change properties on the same Python object.
Authorization requirements:
Object-access permission to the Adapter of this Port.
Task permission to the “Adapter Details” task.
NICs
A NIC (Network Interface Card) is a logical entity that provides a Partition with access to external communication networks through a Network Adapter. More specifically, a NIC connects a Partition with a Network Port, or with a Virtual Switch which then connects to the Network Port.
NIC resources are contained in Partition resources.
NICs only exist in CPCs that are in DPM mode.
- class zhmcclient.NicManager(partition)[source]
Manager providing access to the NICs in a particular Partition.
Derived from
BaseManager
; see there for common methods and attributes.Objects of this class are not directly created by the user; they are accessible via the following instance variable of a
Partition
object (in DPM mode):Attributes:
Partition defining the scope for this manager.
class_name
The resource class name
parent
Subclass of
BaseResource
: Parent resource defining the scope for this manager.resource_class
The Python class of the parent resource of this manager.
session
Session
: Session with the HMC.Methods:
list
([full_properties, filter_args])List the NICs in this Partition.
create
(properties)Create and configure a NIC in this Partition.
__repr__
()Return a string with the state of this manager object, for debug purposes.
find
(**filter_args)Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g.
find_by_name
(name)Find a resource by name (i.e.
find_local
(name, uri[, properties])Return a local resource object without fetching it from the HMC.
findall
(**filter_args)Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g.
flush
()Invalidate the Name-URI cache of this manager.
invalidate_cache
()Invalidate the Name-URI cache of this manager.
resource_object
(uri_or_oid[, props])Return a minimalistic Python resource object for this resource class, that is scoped to this manager.
- list(full_properties=False, filter_args=None)[source]
List the NICs in this Partition.
Authorization requirements:
Object-access permission to this Partition.
- Parameters
full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation.
filter_args (dict) –
Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering.
None causes no filtering to happen, i.e. all resources are returned.
- Returns
A list of
Nic
objects.- Raises
- create(properties)[source]
Create and configure a NIC in this Partition.
The NIC must be backed by an adapter port (on an OSA, ROCE, or Hipersockets adapter).
The way the backing adapter port is specified in the “properties” parameter of this method depends on the adapter type, as follows:
For OSA and Hipersockets adapters, the “virtual-switch-uri” property is used to specify the URI of the virtual switch that is associated with the backing adapter port.
This virtual switch is a resource that automatically exists as soon as the adapter resource exists. Note that these virtual switches do not show up in the HMC GUI; but they do show up at the HMC REST API and thus also at the zhmcclient API as the
VirtualSwitch
class.The value for the “virtual-switch-uri” property can be determined from a given adapter name and port index as shown in the following example code (omitting any error handling):
partition = ... # Partition object for the new NIC adapter_name = 'OSA #1' # name of adapter with backing port adapter_port_index = 0 # port index of backing port adapter = partition.manager.cpc.adapters.find(name=adapter_name) vswitches = partition.manager.cpc.virtual_switches.findall( **{'backing-adapter-uri': adapter.uri}) vswitch = None for vs in vswitches: if vs.get_property('port') == adapter_port_index: vswitch = vs break properties['virtual-switch-uri'] = vswitch.uri
For RoCE adapters, the “network-adapter-port-uri” property is used to specify the URI of the backing adapter port, directly.
The value for the “network-adapter-port-uri” property can be determined from a given adapter name and port index as shown in the following example code (omitting any error handling):
partition = ... # Partition object for the new NIC adapter_name = 'ROCE #1' # name of adapter with backing port adapter_port_index = 0 # port index of backing port adapter = partition.manager.cpc.adapters.find(name=adapter_name) port = adapter.ports.find(index=adapter_port_index) properties['network-adapter-port-uri'] = port.uri
Authorization requirements:
Object-access permission to this Partition.
Object-access permission to the backing Adapter for the new NIC.
Task permission to the “Partition Details” task.
- Parameters
properties (dict) – Initial property values. Allowable properties are defined in section ‘Request body contents’ in section ‘Create NIC’ in the HMC API book.
- Returns
The resource object for the new NIC. The object will have its ‘element-uri’ property set as returned by the HMC, and will also have the input properties set.
- Return type
- Raises
- class zhmcclient.Nic(manager, uri, name=None, properties=None)[source]
Representation of a NIC.
Derived from
BaseResource
; see there for common methods and attributes.For the properties of a NIC resource, see section ‘Data model - NIC Element Object’ in section ‘Partition object’ in the HMC API book.
Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case,
NicManager
).Methods:
delete
()Delete this NIC.
update_properties
(properties)Update writeable properties of this NIC.
__repr__
()Return a string with the state of this resource, for debug purposes.
__str__
()Return a human readable string representation of this resource.
auto_update_enabled
()Return whether auto-update is currently enabled for the resource object.
disable_auto_update
()Disable auto-update for this resource object, if currently enabled.
enable_auto_update
()Enable auto-update for this resource object, if currently disabled.
get_properties_local
(names[, defaults])Return the values of a set of resource properties, using default values for those that are not present in this Python object, without retrieving them from the HMC.
get_property
(name)Return the value of a resource property.
prop
(name[, default])Return the value of a resource property, applying a default if it does not exist.
pull_full_properties
()Retrieve the full set of resource properties and cache them in this object.
update_properties_local
(properties)Update the values of a set of resource properties on this Python object without propagating the updates the HMC.
Attributes:
full_properties
A boolean indicating whether or not the resource properties in this object are the full set of resource properties.
manager
Subclass of
BaseManager
: Manager object for this resource (and for all resources of the same type in the scope of that manager).name
The name of the resource.
properties
The properties of this resource that are currently present in this Python object, as a dictionary.
properties_timestamp
The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).
uri
The canonical URI path of the resource.
- delete()[source]
Delete this NIC.
Authorization requirements:
Object-access permission to the Partition containing this HBA.
Task permission to the “Partition Details” task.
- Raises
- update_properties(properties)[source]
Update writeable properties of this NIC.
This method serializes with other methods that access or change properties on the same Python object.
Authorization requirements:
Object-access permission to the Partition containing this NIC.
Object-access permission to the backing Adapter for this NIC.
Task permission to the “Partition Details” task.
HBAs
A HBA (Host Bus Adapter) is a logical entity that provides a Partition with access to external storage area networks (SANs) through an FCP Adapter. More specifically, an HBA connects a Partition with an Adapter Port on an FCP Adapter.
HBA resources are contained in Partition resources.
HBA resources only exist in CPCs that are in DPM mode and when the “dpm-storage-management” feature is not enabled. See section Storage Groups for details. When the “dpm-storage-management” feature is enabled, virtual HBAs are represented as Virtual Storage Resource resources.
- class zhmcclient.HbaManager(partition)[source]
Manager providing access to the HBAs in a particular Partition.
Derived from
BaseManager
; see there for common methods and attributes.Objects of this class are not directly created by the user; they are accessible via the following instance variable of a
Partition
object (in DPM mode):Note that this instance variable will be None if the “dpm-storage-management” feature is enabled.
Attributes:
Partition defining the scope for this manager.
class_name
The resource class name
parent
Subclass of
BaseResource
: Parent resource defining the scope for this manager.resource_class
The Python class of the parent resource of this manager.
session
Session
: Session with the HMC.Methods:
list
([full_properties, filter_args])List the HBAs in this Partition.
create
(properties)Create and configure an HBA in this Partition.
__repr__
()Return a string with the state of this manager object, for debug purposes.
find
(**filter_args)Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g.
find_by_name
(name)Find a resource by name (i.e.
find_local
(name, uri[, properties])Return a local resource object without fetching it from the HMC.
findall
(**filter_args)Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g.
flush
()Invalidate the Name-URI cache of this manager.
invalidate_cache
()Invalidate the Name-URI cache of this manager.
resource_object
(uri_or_oid[, props])Return a minimalistic Python resource object for this resource class, that is scoped to this manager.
- list(full_properties=False, filter_args=None)[source]
List the HBAs in this Partition.
The returned HBAs have only the ‘element-uri’ property set.
Filtering is supported only for the ‘element-uri’ property.
Authorization requirements:
Object-access permission to this Partition.
- Parameters
full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation.
filter_args (dict) –
Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering.
None causes no filtering to happen, i.e. all resources are returned.
- Returns
A list of
Hba
objects.- Raises
- create(properties)[source]
Create and configure an HBA in this Partition.
The HBA must be backed by an adapter port on an FCP adapter.
The backing adapter port is specified in the “properties” parameter of this method by setting the “adapter-port-uri” property to the URI of the backing adapter port.
The value for the “adapter-port-uri” property can be determined from a given adapter name and port index as shown in the following example code (omitting any error handling):
partition = ... # Partition object for the new HBA adapter_name = 'FCP #1' # name of adapter with backing port adapter_port_index = 0 # port index of backing port adapter = partition.manager.cpc.adapters.find(name=adapter_name) port = adapter.ports.find(index=adapter_port_index) properties['adapter-port-uri'] = port.uri
Authorization requirements:
Object-access permission to this Partition.
Object-access permission to the backing Adapter for the new HBA.
Task permission to the “Partition Details” task.
- Parameters
properties (dict) – Initial property values. Allowable properties are defined in section ‘Request body contents’ in section ‘Create HBA’ in the HMC API book.
- Returns
The resource object for the new HBA. The object will have its ‘element-uri’ property set as returned by the HMC, and will also have the input properties set.
- Return type
- Raises
- class zhmcclient.Hba(manager, uri, name=None, properties=None)[source]
Representation of an HBA.
Derived from
BaseResource
; see there for common methods and attributes.For the properties of an HBA resource, see section ‘Data model - HBA Element Object’ in section ‘Partition object’ in the HMC API book.
Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case,
HbaManager
).Methods:
delete
()Delete this HBA.
update_properties
(properties)Update writeable properties of this HBA.
reassign_port
(port)Reassign this HBA to a new underlying FCP port.
__repr__
()Return a string with the state of this resource, for debug purposes.
__str__
()Return a human readable string representation of this resource.
auto_update_enabled
()Return whether auto-update is currently enabled for the resource object.
disable_auto_update
()Disable auto-update for this resource object, if currently enabled.
enable_auto_update
()Enable auto-update for this resource object, if currently disabled.
get_properties_local
(names[, defaults])Return the values of a set of resource properties, using default values for those that are not present in this Python object, without retrieving them from the HMC.
get_property
(name)Return the value of a resource property.
prop
(name[, default])Return the value of a resource property, applying a default if it does not exist.
pull_full_properties
()Retrieve the full set of resource properties and cache them in this object.
update_properties_local
(properties)Update the values of a set of resource properties on this Python object without propagating the updates the HMC.
Attributes:
full_properties
A boolean indicating whether or not the resource properties in this object are the full set of resource properties.
manager
Subclass of
BaseManager
: Manager object for this resource (and for all resources of the same type in the scope of that manager).name
The name of the resource.
properties
The properties of this resource that are currently present in this Python object, as a dictionary.
properties_timestamp
The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).
uri
The canonical URI path of the resource.
- delete()[source]
Delete this HBA.
Authorization requirements:
Object-access permission to the Partition containing this HBA.
Task permission to the “Partition Details” task.
- Raises
- update_properties(properties)[source]
Update writeable properties of this HBA.
This method serializes with other methods that access or change properties on the same Python object.
Authorization requirements:
Object-access permission to the Partition containing this HBA.
TBD: Verify: Object-access permission to the backing Adapter for this HBA.
Task permission to the “Partition Details” task.
- reassign_port(port)[source]
Reassign this HBA to a new underlying FCP port.
This method performs the HMC operation “Reassign Storage Adapter Port”.
Authorization requirements:
Object-access permission to the Partition containing this HBA.
Object-access permission to the Adapter with the new Port.
Task permission to the “Partition Details” task.
Virtual Functions
A Virtual Function is a logical entity that provides a Partition with access to Accelerator Adapters.
Virtual Function resources are contained in Partition resources.
Virtual Functions only exist in CPCs that are in DPM mode.
- class zhmcclient.VirtualFunctionManager(partition)[source]
Manager providing access to the Virtual Functions in a particular Partition.
Derived from
BaseManager
; see there for common methods and attributes.Objects of this class are not directly created by the user; they are accessible via the following instance variable of a
Partition
object (in DPM mode):Attributes:
Partition defining the scope for this manager.
class_name
The resource class name
parent
Subclass of
BaseResource
: Parent resource defining the scope for this manager.resource_class
The Python class of the parent resource of this manager.
session
Session
: Session with the HMC.Methods:
list
([full_properties, filter_args])List the Virtual Functions of this Partition.
create
(properties)Create a Virtual Function in this Partition.
__repr__
()Return a string with the state of this manager object, for debug purposes.
find
(**filter_args)Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g.
find_by_name
(name)Find a resource by name (i.e.
find_local
(name, uri[, properties])Return a local resource object without fetching it from the HMC.
findall
(**filter_args)Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g.
flush
()Invalidate the Name-URI cache of this manager.
invalidate_cache
()Invalidate the Name-URI cache of this manager.
resource_object
(uri_or_oid[, props])Return a minimalistic Python resource object for this resource class, that is scoped to this manager.
- list(full_properties=False, filter_args=None)[source]
List the Virtual Functions of this Partition.
Authorization requirements:
Object-access permission to this Partition.
- Parameters
full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation.
filter_args (dict) –
Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering.
None causes no filtering to happen, i.e. all resources are returned.
- Returns
A list of
VirtualFunction
objects.- Raises
- create(properties)[source]
Create a Virtual Function in this Partition.
Authorization requirements:
Object-access permission to this Partition.
Object-access permission to the backing accelerator Adapter.
Task permission for the “Partition Details” task.
- Parameters
properties (dict) – Initial property values. Allowable properties are defined in section ‘Request body contents’ in section ‘Create Virtual Function’ in the HMC API book.
- Returns
The resource object for the new Virtual Function. The object will have its ‘element-uri’ property set as returned by the HMC, and will also have the input properties set.
- Return type
- Raises
- class zhmcclient.VirtualFunction(manager, uri, name=None, properties=None)[source]
Representation of a Virtual Function.
Derived from
BaseResource
; see there for common methods and attributes.For the properties of a Virtual Function, see section ‘Data model - Virtual Function Element Object’ in section ‘Partition object’ in the HMC API book.
Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case,
VirtualFunctionManager
).Methods:
delete
()Delete this Virtual Function.
update_properties
(properties)Update writeable properties of this Virtual Function.
__repr__
()Return a string with the state of this resource, for debug purposes.
__str__
()Return a human readable string representation of this resource.
auto_update_enabled
()Return whether auto-update is currently enabled for the resource object.
disable_auto_update
()Disable auto-update for this resource object, if currently enabled.
enable_auto_update
()Enable auto-update for this resource object, if currently disabled.
get_properties_local
(names[, defaults])Return the values of a set of resource properties, using default values for those that are not present in this Python object, without retrieving them from the HMC.
get_property
(name)Return the value of a resource property.
prop
(name[, default])Return the value of a resource property, applying a default if it does not exist.
pull_full_properties
()Retrieve the full set of resource properties and cache them in this object.
update_properties_local
(properties)Update the values of a set of resource properties on this Python object without propagating the updates the HMC.
Attributes:
full_properties
A boolean indicating whether or not the resource properties in this object are the full set of resource properties.
manager
Subclass of
BaseManager
: Manager object for this resource (and for all resources of the same type in the scope of that manager).name
The name of the resource.
properties
The properties of this resource that are currently present in this Python object, as a dictionary.
properties_timestamp
The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).
uri
The canonical URI path of the resource.
- delete()[source]
Delete this Virtual Function.
Authorization requirements:
Object-access permission to the Partition of this Virtual Function.
Task permission for the “Partition Details” task.
- Raises
- update_properties(properties)[source]
Update writeable properties of this Virtual Function.
This method serializes with other methods that access or change properties on the same Python object.
Authorization requirements:
Object-access permission to the Partition of this Virtual Function.
When updating the “adapter-uri” property, object-access permission to the Adapter identified in that URI.
Task permission for the “Partition Details” task.
Virtual Switches
A Virtual Switch is a virtualized networking switch connecting NICs with a Network Port.
Virtual Switches are generated automatically every time a new Network Adapter is detected and configured.
Virtual Switch resources are contained in CPC resources.
Virtual Switches only exist in CPCs that are in DPM mode.
- class zhmcclient.VirtualSwitchManager(cpc)[source]
Manager providing access to the Virtual Switches in a particular CPC.
Derived from
BaseManager
; see there for common methods and attributes.Objects of this class are not directly created by the user; they are accessible via the following instance variable of a
Cpc
object (in DPM mode):Attributes:
CPC defining the scope for this manager.
class_name
The resource class name
parent
Subclass of
BaseResource
: Parent resource defining the scope for this manager.resource_class
The Python class of the parent resource of this manager.
session
Session
: Session with the HMC.Methods:
list
([full_properties, filter_args])List the Virtual Switches in this CPC.
__repr__
()Return a string with the state of this manager object, for debug purposes.
find
(**filter_args)Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g.
find_by_name
(name)Find a resource by name (i.e.
find_local
(name, uri[, properties])Return a local resource object without fetching it from the HMC.
findall
(**filter_args)Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g.
flush
()Invalidate the Name-URI cache of this manager.
invalidate_cache
()Invalidate the Name-URI cache of this manager.
resource_object
(uri_or_oid[, props])Return a minimalistic Python resource object for this resource class, that is scoped to this manager.
- list(full_properties=False, filter_args=None)[source]
List the Virtual Switches in this CPC.
Authorization requirements:
Object-access permission to this CPC.
Object-access permission to the backing Adapters of any Virtual Switches to be included in the result.
- Parameters
full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation.
filter_args (dict) –
Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering.
None causes no filtering to happen, i.e. all resources are returned.
- Returns
A list of
VirtualSwitch
objects.- Raises
- class zhmcclient.VirtualSwitch(manager, uri, name=None, properties=None)[source]
Representation of a Virtual Switch.
Derived from
BaseResource
; see there for common methods and attributes.For the properties of a Virtual Switch, see section ‘Data model’ in section ‘Virtual Switch object’ in the HMC API book.
Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case,
VirtualSwitchManager
).Methods:
List the NICs connected to this Virtual Switch.
update_properties
(properties)Update writeable properties of this Virtual Switch.
__repr__
()Return a string with the state of this resource, for debug purposes.
__str__
()Return a human readable string representation of this resource.
auto_update_enabled
()Return whether auto-update is currently enabled for the resource object.
disable_auto_update
()Disable auto-update for this resource object, if currently enabled.
enable_auto_update
()Enable auto-update for this resource object, if currently disabled.
get_properties_local
(names[, defaults])Return the values of a set of resource properties, using default values for those that are not present in this Python object, without retrieving them from the HMC.
get_property
(name)Return the value of a resource property.
prop
(name[, default])Return the value of a resource property, applying a default if it does not exist.
pull_full_properties
()Retrieve the full set of resource properties and cache them in this object.
update_properties_local
(properties)Update the values of a set of resource properties on this Python object without propagating the updates the HMC.
Attributes:
full_properties
A boolean indicating whether or not the resource properties in this object are the full set of resource properties.
manager
Subclass of
BaseManager
: Manager object for this resource (and for all resources of the same type in the scope of that manager).name
The name of the resource.
properties
The properties of this resource that are currently present in this Python object, as a dictionary.
properties_timestamp
The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).
uri
The canonical URI path of the resource.
- get_connected_nics()[source]
List the NICs connected to this Virtual Switch.
This method performs the “Get Connected VNICs of a Virtual Switch” HMC operation.
Authorization requirements:
Object-access permission to this CPC.
Object-access permission to the backing Adapter of this Virtual Switch.
- update_properties(properties)[source]
Update writeable properties of this Virtual Switch.
This method serializes with other methods that access or change properties on the same Python object.
Authorization requirements:
Object-access permission to the backing Adapter of this Virtual Switch.
Task permission for the “Manage Adapters” task.
Storage Groups
Starting with the z14-ZR1 and LinuxONE Rockhopper II machine generations, the “dpm-storage-management” firmware feature has been introduced to support a simpler management of FCP and FICON (=ECKD) storage for DPM mode. If machines of these generations are in DPM mode, the feature is always enabled and cannot be disabled.
When the “dpm-storage-management” feature is enabled, storage group and storage volume resources can be defined on the HMC, and can cause fulfillment requests to be sent via email to storage administrators. Once these requests are satisfied on the actual storage subsystem and possibly SAN switches, the changes are automatically discovered by DPM and reflected in the state of these resources. Thus, the allocation of actual storage volumes on the storage subsystem is not performed by DPM.
The sending of email is optional, and if the changes are done by some automation tool, they will also be discovered automatically. That way, the whole process of allocating and attaching volumes can be fully automated, if so desired.
The top level resource objects are storage groups.
Storage groups are defined globally at the HMC level, and are associated with a
CPC. They can only be associated with one CPC at a time. In the zhmcclient, the
StorageGroup
objects are accessible via the
storage_groups
property.
Storage groups are a grouping mechanism for storage volumes. An FCP-type storage group can contain only FCP type storage volumes, and a FICON-type storage group can contain only FICON/ECKD type storage volumes.
Attachment and detachment of volumes to a partition happens at the level of storage groups, and always applies to all volumes defined in the storage group.
The storage-related z/Architecture devices that are visible to a partition are different for the two storage architectures: For FCP, the virtualized HBA is visible as a device, and the storage volumes (LUNs) are not represented as devices. For FICON, each ECKD volume is visible as a device, but the virtualized FICON adapter port is not represented as a device. When the “dpm-storage-management” feature is enabled, each storage-related z/Architecture device that is visible to a partition is represented as a virtual storage resource object. The virtual storage resource objects are instantiated automatically when a storage group is attached to a partition. The HBA resource objects known from DPM mode before the introduction of the “dpm-storage-management” feature are not exposed anymore (their equivalent are now the virtual storage resource objects).
Single storage volumes cannot be attached to partitions, only entire storage groups can be. In fact, storage volume objects do not even exist outside the scope of storage groups. A particular storage volume can be contained in only one storage group.
Storage groups can be listed, created, deleted, and updated, and their storage volumes can also be listed, created, deleted, and updated.
Storage groups can be attached to zero or more partitions. Attachment to multiple partitions at the same time is possible for storage groups that are defined to be shareable. In case of multiple attachments of a storage group, it contains the storage volume objects only once for all attachments, but the virtual storage resource objects are instantiated separately for each attachment.
Storage groups can only be associated with CPCs that have the “dpm-storage-management” feature enabled.
- class zhmcclient.StorageGroupManager(console)[source]
Manager providing access to the storage groups of the HMC.
Derived from
BaseManager
; see there for common methods and attributes.Objects of this class are not directly created by the user; they are accessible via the following instance variable:
storage_groups
of aConsole
object.
Attributes:
The Console object representing the HMC.
class_name
The resource class name
parent
Subclass of
BaseResource
: Parent resource defining the scope for this manager.resource_class
The Python class of the parent resource of this manager.
session
Session
: Session with the HMC.Methods:
list
([full_properties, filter_args])List the storage groups defined in the HMC.
create
([properties, template])Create and configure a storage group either from input properties or from a storage group template.
__repr__
()Return a string with the state of this manager object, for debug purposes.
find
(**filter_args)Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g.
find_by_name
(name)Find a resource by name (i.e.
find_local
(name, uri[, properties])Return a local resource object without fetching it from the HMC.
findall
(**filter_args)Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g.
flush
()Invalidate the Name-URI cache of this manager.
invalidate_cache
()Invalidate the Name-URI cache of this manager.
resource_object
(uri_or_oid[, props])Return a minimalistic Python resource object for this resource class, that is scoped to this manager.
- list(full_properties=False, filter_args=None)[source]
List the storage groups defined in the HMC.
Storage groups for which the authenticated user does not have object-access permission are not included.
Authorization requirements:
Object-access permission to any storage groups to be included in the result.
- Parameters
full_properties (bool) – Controls that the full set of resource properties for each returned storage volume is being retrieved, vs. only the following short set: “object-uri”, “cpc-uri”, “name”, “fulfillment-state”, and “type”.
filter_args (dict) –
Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering.
None causes no filtering to happen.
- Returns
A list of
StorageGroup
objects.- Raises
- create(properties=None, template=None)[source]
Create and configure a storage group either from input properties or from a storage group template.
The input properties may specify initial storage volumes for the new storage group via the storage-volumes property. Additional storage volumes can be added with
update_properties()
.A storage group template can also specify initial storage volumes for the new storage group. For details, see
StorageGroupTemplate
.The new storage group will be associated with the CPC identified by the cpc-uri input property.
Authorization requirements:
Object-access permission to the CPC that will be associated with the new storage group.
Task permission to the “Configure Storage - System Programmer” task.
- Parameters
properties (dict) –
Initial property values. Allowable properties are defined in section ‘Request body contents’ in section ‘Create Storage Group’ in the HMC API book.
The ‘cpc-uri’ property identifies the CPC to which the new storage group will be associated, and is required to be specified in this parameter.
The ‘template-uri’ property is not allowed. If you want to create a storage group from a storage group template, specify the template parameter.
The properties and template parameters are mutually exclusive.
template (
StorageGroupTemplate
) – storage group template defining the initial property values for the storage group, including its initial storage volumes.
- Returns
The resource object for the new storage group. The object will have its ‘object-uri’ property set as returned by the HMC, and will also have the input properties set.
- Return type
- Raises
- class zhmcclient.StorageGroup(manager, uri, name=None, properties=None)[source]
Representation of a storage group.
Derived from
BaseResource
; see there for common methods and attributes.Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case,
StorageGroupManager
).Attributes:
Access to the storage volumes in this storage group.
Access to the virtual storage resources in this storage group.
The CPC to which this storage group is associated.
full_properties
A boolean indicating whether or not the resource properties in this object are the full set of resource properties.
manager
Subclass of
BaseManager
: Manager object for this resource (and for all resources of the same type in the scope of that manager).name
The name of the resource.
properties
The properties of this resource that are currently present in this Python object, as a dictionary.
properties_timestamp
The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).
uri
The canonical URI path of the resource.
Methods:
list_attached_partitions
([name, status])Return the partitions to which this storage group is currently attached, optionally filtered by partition name and status.
delete
([email_to_addresses, ...])Delete this storage group and its storage volume resources on the HMC, and optionally send emails to storage administrators requesting deletion of the storage volumes on the storage subsystem and cleanup of any resources related to the storage group (e.g.
update_properties
(properties)Update writeable properties of this storage group.
add_candidate_adapter_ports
(ports)Add a list of storage adapter ports to this storage group's candidate adapter ports list.
Remove a list of storage adapter ports from this storage group's candidate adapter ports list.
list_candidate_adapter_ports
([full_properties])Return the current candidate storage adapter port list of this storage group.
discover_fcp
([force_restart, ...])Perform Logical Unit Number (LUN) discovery for this FCP storage group.
Get the latest connection report for this storage group.
__repr__
()Return a string with the state of this resource, for debug purposes.
__str__
()Return a human readable string representation of this resource.
auto_update_enabled
()Return whether auto-update is currently enabled for the resource object.
disable_auto_update
()Disable auto-update for this resource object, if currently enabled.
enable_auto_update
()Enable auto-update for this resource object, if currently disabled.
get_properties_local
(names[, defaults])Return the values of a set of resource properties, using default values for those that are not present in this Python object, without retrieving them from the HMC.
get_property
(name)Return the value of a resource property.
prop
(name[, default])Return the value of a resource property, applying a default if it does not exist.
pull_full_properties
()Retrieve the full set of resource properties and cache them in this object.
update_properties_local
(properties)Update the values of a set of resource properties on this Python object without propagating the updates the HMC.
- property storage_volumes
Access to the storage volumes in this storage group.
- Type
- property virtual_storage_resources
Access to the virtual storage resources in this storage group.
- property cpc
The CPC to which this storage group is associated.
The returned
Cpc
has only a minimal set of properties populated.- Type
- list_attached_partitions(name=None, status=None)[source]
Return the partitions to which this storage group is currently attached, optionally filtered by partition name and status.
Authorization requirements:
Object-access permission to this storage group.
Task permission to the “Configure Storage - System Programmer” task.
- Parameters
name (string) – Filter pattern (regular expression) to limit returned partitions to those that have a matching name. If None, no filtering for the partition name takes place.
status (string) – Filter string to limit returned partitions to those that have a matching status. The value must be a valid partition status property value. If None, no filtering for the partition status takes place.
- Returns
List of
Partition
objects representing the partitions to whivch this storage group is currently attached, with a minimal set of properties (‘object-id’, ‘name’, ‘status’).- Raises
- delete(email_to_addresses=None, email_cc_addresses=None, email_insert=None)[source]
Delete this storage group and its storage volume resources on the HMC, and optionally send emails to storage administrators requesting deletion of the storage volumes on the storage subsystem and cleanup of any resources related to the storage group (e.g. zones on a SAN switch, or host objects on a storage subsystem).
Authorization requirements:
Object-access permission to this storage group.
Task permission to the “Configure Storage - System Programmer” task.
- Parameters
email_to_addresses (iterable of string) – Email addresses of one or more storage administrator to be notified. If None or empty, no email will be sent.
email_cc_addresses (iterable of string) – Email addresses of one or more storage administrator to be copied on the notification email. If None or empty, nobody will be copied on the email. Must be None or empty if email_to_addresses is None or empty.
email_insert (string) – Additional text to be inserted in the notification email. The text can include HTML formatting tags. If None, no additional text will be inserted. Must be None or empty if email_to_addresses is None or empty.
- Raises
ValueError – Incorrect input arguments
- update_properties(properties)[source]
Update writeable properties of this storage group.
This includes the storage-volumes property which contains requests for creations, deletions and updates of
StorageVolume
resources of this storage group. As an alternative to this bulk approach for managing storage volumes, eachStorageVolume
resource can individually be created, deleted and updated using the respective methods onstorage_volumes
.This method serializes with other methods that access or change properties on the same Python object.
Authorization requirements:
Object-access permission to this storage group.
Task permission to the “Configure Storage - System Programmer” task.
- Parameters
properties (dict) – New values for the properties to be updated. Properties not to be updated are omitted. Allowable properties are listed for operation ‘Modify Storage Group Properties’ in section ‘Storage Group object’ in the HMC API book. This includes the email addresses of the storage administrators.
- Raises
- add_candidate_adapter_ports(ports)[source]
Add a list of storage adapter ports to this storage group’s candidate adapter ports list.
This operation only applies to storage groups of type “fcp”.
These adapter ports become candidates for use as backing adapters when creating virtual storage resources when the storage group is attached to a partition. The adapter ports should have connectivity to the storage area network (SAN).
Candidate adapter ports may only be added before the CPC discovers a working communications path, indicated by a “verified” status on at least one of this storage group’s WWPNs. After that point, all adapter ports in the storage group are automatically detected and manually adding them is no longer possible.
Because the CPC discovers working communications paths automatically, candidate adapter ports do not need to be added by the user. Any ports that are added, are validated by the CPC during discovery, and may or may not actually be used.
Authorization requirements:
Object-access permission to this storage group.
Object-access permission to the adapter of each specified port.
Task permission to the “Configure Storage - System Programmer” task.
- remove_candidate_adapter_ports(ports)[source]
Remove a list of storage adapter ports from this storage group’s candidate adapter ports list.
This operation only applies to storage groups of type “fcp”.
Because the CPC discovers working communications paths automatically, candidate adapter ports do not need to be managed by the user. Any ports that are removed using this function, might actually be added again by the CPC dependent on the results of discovery.
Authorization requirements:
Object-access permission to this storage group.
Object-access permission to the adapter of each specified port.
Task permission to the “Configure Storage - System Programmer” task.
- list_candidate_adapter_ports(full_properties=False)[source]
Return the current candidate storage adapter port list of this storage group.
The result reflects the actual list of ports used by the CPC, including any changes that have been made during discovery. The source for this information is the ‘candidate-adapter-port-uris’ property of the storage group object.
- Parameters
full_properties (bool) –
Controls that the full set of resource properties for each returned candidate storage adapter port is being retrieved, vs. only the following short set: “element-uri”, “element-id”, “class”, “parent”.
TODO: Verify short list of properties.
- Returns
List of
Port
objects representing the current candidate storage adapter ports of this storage group.- Raises
- discover_fcp(force_restart=False, wait_for_completion=True, operation_timeout=None)[source]
Perform Logical Unit Number (LUN) discovery for this FCP storage group. The corresponding HMC operation is “Start FCP Storage Discovery”.
This operation only applies to storage groups of type “fcp”.
The HMC performs the LUN discovery in an asynchronous job. This method supports waiting for completion of the job and thus the LUN discovery, or returning immediately after the HMC has started the asynchronous job.
When the LUN discovery is completed, a connection report will have been created that reflects the results of the discovery. The connection report can be retrieved with
get_connection_report()
. It is recommended to retrieve the connection report and verify that it reports correct volumes.Authorization requirements:
Object-access permission to this storage group.
Task permission to the “Configure Storage - System Programmer” task or to the “Configure Storage - Storage Administrator” task.
- Parameters
force_restart (bool) – Indicates if there is an in-progress discovery operation for the specified storage group, it should be terminated and started again. If False or there is no in-progress discovery operation for the specified storage group, a new one is started.
wait_for_completion (bool) – Boolean controlling whether this method should wait for completion of the asynchronous job performing the LUN discovery.
operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the LUN discovery. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a
OperationTimeout
is raised.
- Returns
If wait_for_completion is True, returns nothing.
If wait_for_completion is False, returns a
Job
object representing the asynchronously executing job on the HMC.- Return type
None or
Job
- Raises
OperationTimeout – The timeout expired while waiting for completion of the operation.
- get_connection_report()[source]
Get the latest connection report for this storage group.
The corresponding HMC operation is “Get Connection Report”.
The connection report is updated when LUN discovery is performed. LUN discovery for FCP storage groups is performed automatically based on certain triggers, and regularly every 10 minutes, and can additionally be triggered with
discover_fcp()
.To verify that the correct volumes are reported for an FCP storage group, verify that the property volumes-configuration-status has a value of “correct-volumes” for all WWPNs in all FCP subsystems:
report = storage_group.get_connection_report() for subsys in report['fcp-storage-subsystems']: for config in subsys['storage-configurations']: if config['volumes-configuration-status'] != "correct-volumes": # report incorrect volumes
Authorization requirements:
Object-access permission to this storage group.
Task permission to the “Configure Storage - System Programmer” task or to the “Configure Storage - Storage Administrator” task.
- Returns
A JSON object with the connection report. For details about the items in the JSON object, see section ‘Response body contents’ in section ‘Get Connection Report’ in the HMC API book.
- Return type
- Raises
Storage Volumes
A StorageVolume
object represents an FCP or FICON (ECKD)
storage volume that is defined in a storage group.
Storage volume objects can be created, but what is created is the definition of a storage volume in the HMC and CPC. This does not include the act of actually allocating the volume on a storage subsystem. That is performed by a storage administrator who fulfills the volumes.
In order to represent that, storage volume objects have a fulfillment state that is available in their ‘fulfillment-state’ property.
When a storage group is attached to a partition, the group’s storage volumes are attached to the partition and any virtual storage resource objects are instantiated.
Storage volumes are contained in storage groups.
You can create as many storage volumes as you want in a storage group.
Storage groups and storage volumes only can be defined in CPCs that are in DPM mode and that have the “dpm-storage-management” feature enabled.
- class zhmcclient.StorageVolumeManager(storage_group)[source]
Manager providing access to the storage volumes in a particular storage group.
Derived from
BaseManager
; see there for common methods and attributes.Objects of this class are not directly created by the user; they are accessible via the following instance variable of a
StorageGroup
object:Attributes:
Storage group defining the scope for this manager.
class_name
The resource class name
parent
Subclass of
BaseResource
: Parent resource defining the scope for this manager.resource_class
The Python class of the parent resource of this manager.
session
Session
: Session with the HMC.Methods:
list
([full_properties, filter_args])List the storage volumes in this storage group.
create
(properties[, email_to_addresses, ...])Create a storage volume in this storage group on the HMC, and optionally send emails to storage administrators requesting creation of the storage volume on the storage subsystem and setup of any resources related to the storage volume (e.g.
__repr__
()Return a string with the state of this manager object, for debug purposes.
find
(**filter_args)Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g.
find_by_name
(name)Find a resource by name (i.e.
find_local
(name, uri[, properties])Return a local resource object without fetching it from the HMC.
findall
(**filter_args)Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g.
flush
()Invalidate the Name-URI cache of this manager.
invalidate_cache
()Invalidate the Name-URI cache of this manager.
resource_object
(uri_or_oid[, props])Return a minimalistic Python resource object for this resource class, that is scoped to this manager.
- property storage_group
Storage group defining the scope for this manager.
- Type
- list(full_properties=False, filter_args=None)[source]
List the storage volumes in this storage group.
Authorization requirements:
Object-access permission to this storage group.
- Parameters
full_properties (bool) – Controls that the full set of resource properties for each returned storage volume is being retrieved, vs. only the following short set: “element-uri”, “name”, “fulfillment-state”, “size”, and “usage”.
filter_args (dict) –
Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering.
None causes no filtering to happen, i.e. all resources are returned.
- Returns
A list of
StorageVolume
objects.- Raises
- create(properties, email_to_addresses=None, email_cc_addresses=None, email_insert=None)[source]
Create a storage volume in this storage group on the HMC, and optionally send emails to storage administrators requesting creation of the storage volume on the storage subsystem and setup of any resources related to the storage volume (e.g. LUN mask definition on the storage subsystem).
This method performs the “Modify Storage Group Properties” operation, requesting creation of the volume.
Authorization requirements:
Object-access permission to this storage group.
Task permission to the “Configure Storage - System Programmer” task.
- Parameters
properties (dict) –
Initial property values for the new volume.
Allowable properties are the fields defined in the “storage-volume-request-info” nested object described for operation “Modify Storage Group Properties” in the HMC API book. The valid fields are those for the “create” operation. The operation field must not be provided; it is set automatically to the value “create”.
The properties provided in this parameter will be copied and then amended with the operation=”create” field, and then used as a single array item for the storage-volumes field in the request body of the “Modify Storage Group Properties” operation.
Note that for storage volumes, the HMC does auto-generate a value for the “name” property, but that auto-generated name is not unique within the parent storage group. If you depend on a unique name, you need to specify a “name” property accordingly.
email_to_addresses (iterable of string) – Email addresses of one or more storage administrator to be notified. If None or empty, no email will be sent.
email_cc_addresses (iterable of string) – Email addresses of one or more storage administrator to be copied on the notification email. If None or empty, nobody will be copied on the email. Must be None or empty if email_to_addresses is None or empty.
email_insert (string) – Additional text to be inserted in the notification email. The text can include HTML formatting tags. If None, no additional text will be inserted. Must be None or empty if email_to_addresses is None or empty.
- Returns
The resource object for the new storage volume. The object will have the following properties set:
’element-uri’ as returned by the HMC
’element-id’ as determined from the ‘element-uri’ property
’class’ and ‘parent’
additional properties as specified in the input properties
- Return type
- Raises
Example:
stovol1 = fcp_stogrp.storage_volumes.create( properties=dict( name='vol1', size=30, # GiB ))
- class zhmcclient.StorageVolume(manager, uri, name=None, properties=None)[source]
Representation of a storage volume.
Derived from
BaseResource
; see there for common methods and attributes.Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case,
StorageVolumeManager
).Attributes:
term unicode string: The object ID of this storage volume.
full_properties
A boolean indicating whether or not the resource properties in this object are the full set of resource properties.
manager
Subclass of
BaseManager
: Manager object for this resource (and for all resources of the same type in the scope of that manager).name
The name of the resource.
properties
The properties of this resource that are currently present in this Python object, as a dictionary.
properties_timestamp
The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).
uri
The canonical URI path of the resource.
Methods:
delete
([email_to_addresses, ...])Delete this storage volume on the HMC, and optionally send emails to storage administrators requesting deletion of the storage volume on the storage subsystem and cleanup of any resources related to the storage volume (e.g.
update_properties
(properties[, ...])Update writeable properties of this storage volume on the HMC, and optionally send emails to storage administrators requesting modification of the storage volume on the storage subsystem and of any resources related to the storage volume.
indicate_fulfillment_ficon
(control_unit, ...)TODO: Add ControlUnit objects etc for FICON support.
indicate_fulfillment_fcp
(wwpn, lun, host_port)Indicate completion of fulfillment for this FCP storage volume and provide identifying information (WWPN and LUN) about the actual storage volume on the storage subsystem.
__repr__
()Return a string with the state of this resource, for debug purposes.
__str__
()Return a human readable string representation of this resource.
auto_update_enabled
()Return whether auto-update is currently enabled for the resource object.
disable_auto_update
()Disable auto-update for this resource object, if currently enabled.
enable_auto_update
()Enable auto-update for this resource object, if currently disabled.
get_properties_local
(names[, defaults])Return the values of a set of resource properties, using default values for those that are not present in this Python object, without retrieving them from the HMC.
get_property
(name)Return the value of a resource property.
prop
(name[, default])Return the value of a resource property, applying a default if it does not exist.
pull_full_properties
()Retrieve the full set of resource properties and cache them in this object.
update_properties_local
(properties)Update the values of a set of resource properties on this Python object without propagating the updates the HMC.
- property oid
term unicode string: The object ID of this storage volume. The object ID is unique within the parent storage group.
Note that for storage volumes, the ‘name’ property is not unique and therefore cannot be used to identify a storage volume. Therefore, storage volumes provide easy access to the object ID, as a means to identify the storage volume in CLIs and other string-based tooling.
- delete(email_to_addresses=None, email_cc_addresses=None, email_insert=None)[source]
Delete this storage volume on the HMC, and optionally send emails to storage administrators requesting deletion of the storage volume on the storage subsystem and cleanup of any resources related to the storage volume (e.g. LUN mask definitions on a storage subsystem).
This method performs the “Modify Storage Group Properties” operation, requesting deletion of the volume.
Authorization requirements:
Object-access permission to the storage group owning this storage volume.
Task permission to the “Configure Storage - System Programmer” task.
- Parameters
email_to_addresses (iterable of string) – Email addresses of one or more storage administrator to be notified. If None or empty, no email will be sent.
email_cc_addresses (iterable of string) – Email addresses of one or more storage administrator to be copied on the notification email. If None or empty, nobody will be copied on the email. Must be None or empty if email_to_addresses is None or empty.
email_insert (string) – Additional text to be inserted in the notification email. The text can include HTML formatting tags. If None, no additional text will be inserted. Must be None or empty if email_to_addresses is None or empty.
- Raises
- update_properties(properties, email_to_addresses=None, email_cc_addresses=None, email_insert=None)[source]
Update writeable properties of this storage volume on the HMC, and optionally send emails to storage administrators requesting modification of the storage volume on the storage subsystem and of any resources related to the storage volume.
This method performs the “Modify Storage Group Properties” operation, requesting modification of the volume.
This method serializes with other methods that access or change properties on the same Python object.
Authorization requirements:
Object-access permission to the storage group owning this storage volume.
Task permission to the “Configure Storage - System Programmer” task.
- Parameters
properties (dict) –
New property values for the volume. Allowable properties are the fields defined in the “storage-volume-request-info” nested object for the “modify” operation. That nested object is described in section “Request body contents” for operation “Modify Storage Group Properties” in the HMC API book.
The properties provided in this parameter will be copied and then amended with the operation=”modify” and element-uri properties, and then used as a single array item for the storage-volumes field in the request body of the “Modify Storage Group Properties” operation.
email_to_addresses (iterable of string) – Email addresses of one or more storage administrator to be notified. If None or empty, no email will be sent.
email_cc_addresses (iterable of string) – Email addresses of one or more storage administrator to be copied on the notification email. If None or empty, nobody will be copied on the email. Must be None or empty if email_to_addresses is None or empty.
email_insert (string) – Additional text to be inserted in the notification email. The text can include HTML formatting tags. If None, no additional text will be inserted. Must be None or empty if email_to_addresses is None or empty.
- Raises
- indicate_fulfillment_ficon(control_unit, unit_address)[source]
TODO: Add ControlUnit objects etc for FICON support.
Indicate completion of fulfillment for this ECKD (=FICON) storage volume and provide identifying information (control unit and unit address) about the actual storage volume on the storage subsystem.
Manually indicating fulfillment is required for all ECKD volumes, because they are not auto-discovered by the CPC.
This method performs the “Fulfill FICON Storage Volume” HMC operation.
Upon successful completion of this operation, the “fulfillment-state” property of this storage volume object will have been set to “complete”. That is necessary for the CPC to be able to address and connect to the volume.
If the “fulfillment-state” properties of all storage volumes in the owning storage group are “complete”, the owning storage group’s “fulfillment-state” property will also be set to “complete”.
- Parameters
control_unit (
ControlUnit
) – Logical control unit (LCU) in which the backing ECKD volume is defined.unit_address (string) – Unit address of the backing ECKD volume within its logical control unit, as a hexadecimal number of up to 2 characters in any lexical case.
Authorization requirements:
Object-access permission to the storage group owning this storage volume.
Task permission to the “Configure Storage - Storage Administrator” task.
- Raises
- indicate_fulfillment_fcp(wwpn, lun, host_port)[source]
Indicate completion of fulfillment for this FCP storage volume and provide identifying information (WWPN and LUN) about the actual storage volume on the storage subsystem.
Manually indicating fulfillment is required for storage volumes that will be used as boot devices for a partition. The specified host port will be used to access the storage volume during boot of the partition.
Because the CPC discovers storage volumes automatically, the fulfillment of non-boot volumes does not need to be manually indicated using this function (it may be indicated though before the CPC discovers a working communications path to the volume, but the role of the specified host port is not clear in this case).
This method performs the “Fulfill FCP Storage Volume” HMC operation.
Upon successful completion of this operation, the “fulfillment-state” property of this storage volume object will have been set to “complete”. That is necessary for the CPC to be able to address and connect to the volume.
If the “fulfillment-state” properties of all storage volumes in the owning storage group are “complete”, the owning storage group’s “fulfillment-state” property will also be set to “complete”.
- Parameters
wwpn (string) – World wide port name (WWPN) of the FCP storage subsystem containing the storage volume, as a hexadecimal number of up to 16 characters in any lexical case.
lun (string) – Logical Unit Number (LUN) of the storage volume within its FCP storage subsystem, as a hexadecimal number of up to 16 characters in any lexical case.
host_port (
Port
) – Storage port on the CPC that will be used to boot from.
Authorization requirements:
Object-access permission to the storage group owning this storage volume.
Task permission to the “Configure Storage - Storage Administrator” task.
- Raises
Virtual Storage Resources
A virtual storage resource object represents a storage-related z/Architecture device that is visible to a partition and that provides access for that partition to a storage volume.
The storage-related z/Architecture devices that are visible to a partition are different for the two storage architectures: For FCP, the virtualized HBA is visible as a device, and the storage volumes (LUNs) are not represented as devices. For FICON, each ECKD volume is visible as a device, but the virtualized FICON adapter port is not represented as a device.
What the virtual storage resource objects represent, therefore depends on the storage architecture of the storage volume they are used for:
For FCP, a virtual storage resource object represents the virtualized HBA in the partition that is used to access the LUN. However, each usage of the virtual HBA in context of a storage group has its own virtual storage resource object.
For FICON, a virtual storage resource object represents the ECKD volume.
Virtual storage resource objects are instantiated automatically when a storage group is attached to a partition, and are removed automatically upon detachment.
The HBA resource objects known from DPM mode before introduction of the “dpm-storage-management” feature are no longer exposed.
Virtual storage resource objects are contained in storage group objects.
Storage groups and storage volumes only can be defined in CPCs that are in DPM mode and that have the “dpm-storage-management” feature enabled.
- class zhmcclient.VirtualStorageResourceManager(storage_group)[source]
Manager providing access to the virtual storage resources in a particular storage group.
Derived from
BaseManager
; see there for common methods and attributes.Objects of this class are not directly created by the user; they are accessible via the following instance variable of a
StorageGroup
object:Attributes:
Storage group defining the scope for this manager.
class_name
The resource class name
parent
Subclass of
BaseResource
: Parent resource defining the scope for this manager.resource_class
The Python class of the parent resource of this manager.
session
Session
: Session with the HMC.Methods:
list
([full_properties, filter_args])List the virtual storage resources in this storage group.
__repr__
()Return a string with the state of this manager object, for debug purposes.
find
(**filter_args)Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g.
find_by_name
(name)Find a resource by name (i.e.
find_local
(name, uri[, properties])Return a local resource object without fetching it from the HMC.
findall
(**filter_args)Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g.
flush
()Invalidate the Name-URI cache of this manager.
invalidate_cache
()Invalidate the Name-URI cache of this manager.
resource_object
(uri_or_oid[, props])Return a minimalistic Python resource object for this resource class, that is scoped to this manager.
- property storage_group
Storage group defining the scope for this manager.
- Type
- list(full_properties=False, filter_args=None)[source]
List the virtual storage resources in this storage group.
Authorization requirements:
Object-access permission to this storage group.
- Parameters
full_properties (bool) – Controls that the full set of resource properties for each returned storage volume is being retrieved, vs. only the following short set: “element-uri”, “name”, “device-number”, “adapter-port-uri”, and “partition-uri”.
filter_args (dict) –
Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering.
None causes no filtering to happen, i.e. all resources are returned.
- Returns
A list of
VirtualStorageResource
objects.- Raises
- class zhmcclient.VirtualStorageResource(manager, uri, name=None, properties=None)[source]
Representation of a virtual storage resource.
Derived from
BaseResource
; see there for common methods and attributes.Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case,
VirtualStorageResourceManager
).Attributes:
The partition to which this virtual storage resource is attached.
The storage adapter port associated with this virtual storage resource, once discovery has determined which port to use for this virtual storage resource.
full_properties
A boolean indicating whether or not the resource properties in this object are the full set of resource properties.
manager
Subclass of
BaseManager
: Manager object for this resource (and for all resources of the same type in the scope of that manager).name
The name of the resource.
properties
The properties of this resource that are currently present in this Python object, as a dictionary.
properties_timestamp
The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).
uri
The canonical URI path of the resource.
Methods:
update_properties
(properties)Update writeable properties of this virtual storage resource.
__repr__
()Return a string with the state of this resource, for debug purposes.
__str__
()Return a human readable string representation of this resource.
auto_update_enabled
()Return whether auto-update is currently enabled for the resource object.
disable_auto_update
()Disable auto-update for this resource object, if currently enabled.
enable_auto_update
()Enable auto-update for this resource object, if currently disabled.
get_properties_local
(names[, defaults])Return the values of a set of resource properties, using default values for those that are not present in this Python object, without retrieving them from the HMC.
get_property
(name)Return the value of a resource property.
prop
(name[, default])Return the value of a resource property, applying a default if it does not exist.
pull_full_properties
()Retrieve the full set of resource properties and cache them in this object.
update_properties_local
(properties)Update the values of a set of resource properties on this Python object without propagating the updates the HMC.
- property attached_partition
The partition to which this virtual storage resource is attached.
The returned partition object has only a minimal set of properties set (‘object-id’, ‘object-uri’, ‘class’, ‘parent’).
Note that a virtual storage resource is always attached to a partition, as long as it exists.
Authorization requirements:
Object-access permission to the storage group owning this virtual storage resource.
- Raises
- Type
- property adapter_port
The storage adapter port associated with this virtual storage resource, once discovery has determined which port to use for this virtual storage resource.
This applies to both, FCP and FICON/ECKD typed storage groups.
The returned adapter port object has only a minimal set of properties set (‘object-id’, ‘object-uri’, ‘class’, ‘parent’).
Authorization requirements:
Object-access permission to the storage group owning this virtual storage resource.
Object-access permission to the CPC of the storage adapter.
Object-access permission to the storage adapter.
- Raises
- Type
- update_properties(properties)[source]
Update writeable properties of this virtual storage resource.
This method serializes with other methods that access or change properties on the same Python object.
Authorization requirements:
Object-access permission to the storage group owning this virtual storage resource.
Task permission to the “Configure Storage - System Programmer” task.
Storage Group Templates
A StorageGroupTemplate
object represents a
storage group template object and can be used to create
storage group objects with the properties of the template, including an
initial set of storage volumes, using the
zhmcclient.StorageGroupTemplateManager.create()
method.
Storage group template objects can be created, updated and deleted.
Storage group template objects can only be defined in CPCs that are in DPM mode and that have the “dpm-storage-management” feature enabled.
- class zhmcclient.StorageGroupTemplateManager(console)[source]
Manager providing access to the storage group templates of the HMC.
Derived from
BaseManager
; see there for common methods and attributes.Objects of this class are not directly created by the user; they are accessible via the following instance variable:
storage_group_templates
of aConsole
object.
Attributes:
The Console object representing the HMC.
class_name
The resource class name
parent
Subclass of
BaseResource
: Parent resource defining the scope for this manager.resource_class
The Python class of the parent resource of this manager.
session
Session
: Session with the HMC.Methods:
list
([full_properties, filter_args])List the storage group templates defined in the HMC.
create
(properties)Create a storage group template.
__repr__
()Return a string with the state of this manager object, for debug purposes.
find
(**filter_args)Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g.
find_by_name
(name)Find a resource by name (i.e.
find_local
(name, uri[, properties])Return a local resource object without fetching it from the HMC.
findall
(**filter_args)Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g.
flush
()Invalidate the Name-URI cache of this manager.
invalidate_cache
()Invalidate the Name-URI cache of this manager.
resource_object
(uri_or_oid[, props])Return a minimalistic Python resource object for this resource class, that is scoped to this manager.
- list(full_properties=False, filter_args=None)[source]
List the storage group templates defined in the HMC.
Storage group templates for which the authenticated user does not have object-access permission are not included.
Authorization requirements:
Object-access permission to any storage group templates to be included in the result.
- Parameters
full_properties (bool) – Controls that the full set of resource properties for each returned storage group template is being retrieved, vs. only the following short set: “object-uri”, “cpc-uri”, “name”, and “type”.
filter_args (dict) –
Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering.
None causes no filtering to happen.
- Returns
A list of
StorageGroupTemplate
objects.- Raises
- create(properties)[source]
Create a storage group template.
The new storage group will be associated with the CPC identified by the cpc-uri input property.
Authorization requirements:
Object-access permission to the CPC that will be associated with the new storage group template.
Task permission to the “Configure Storage - System Programmer” task.
- Parameters
properties (dict) –
Initial property values. Allowable properties are defined in section ‘Request body contents’ in section ‘Create Storage Template’ in the HMC API book.
The ‘cpc-uri’ property identifies the CPC to which the new storage group template will be associated, and is required to be specified in this parameter.
- Returns
The resource object for the new storage group template. The object will have its ‘object-uri’ property set as returned by the HMC, and will also have the input properties set.
- Return type
- Raises
- class zhmcclient.StorageGroupTemplate(manager, uri, name=None, properties=None)[source]
Representation of a storage group template.
Derived from
BaseResource
; see there for common methods and attributes.Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case,
StorageGroupTemplateManager
).Attributes:
Access to the storage volumes in this storage group.
The CPC to which this storage group template is associated.
full_properties
A boolean indicating whether or not the resource properties in this object are the full set of resource properties.
manager
Subclass of
BaseManager
: Manager object for this resource (and for all resources of the same type in the scope of that manager).name
The name of the resource.
properties
The properties of this resource that are currently present in this Python object, as a dictionary.
properties_timestamp
The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).
uri
The canonical URI path of the resource.
Methods:
delete
()Delete this storage group template and its storage volume template resources on the HMC.
update_properties
(properties)Update writeable properties of this storage group template.
__repr__
()Return a string with the state of this resource, for debug purposes.
__str__
()Return a human readable string representation of this resource.
auto_update_enabled
()Return whether auto-update is currently enabled for the resource object.
disable_auto_update
()Disable auto-update for this resource object, if currently enabled.
enable_auto_update
()Enable auto-update for this resource object, if currently disabled.
get_properties_local
(names[, defaults])Return the values of a set of resource properties, using default values for those that are not present in this Python object, without retrieving them from the HMC.
get_property
(name)Return the value of a resource property.
prop
(name[, default])Return the value of a resource property, applying a default if it does not exist.
pull_full_properties
()Retrieve the full set of resource properties and cache them in this object.
update_properties_local
(properties)Update the values of a set of resource properties on this Python object without propagating the updates the HMC.
- property storage_volume_templates
Access to the storage volumes in this storage group.
- Type
- property cpc
The CPC to which this storage group template is associated.
The returned
Cpc
has only a minimal set of properties populated.- Type
- delete()[source]
Delete this storage group template and its storage volume template resources on the HMC.
Storage groups and their volumes that have been created from the template that is deleted, are not affected.
Authorization requirements:
Object-access permission to this storage group template.
Task permission to the “Configure Storage - System Programmer” task.
- Raises
- update_properties(properties)[source]
Update writeable properties of this storage group template.
This includes the storage-template-volumes property which contains requests for creations, deletions and updates of
StorageVolumeTemplate
resources of this storage group template.As an alternative to this bulk approach for managing storage volume templates, each
StorageVolumeTemplate
resource can individually be created, deleted and updated using the respective methods onstorage_volume_templates
.This method serializes with other methods that access or change properties on the same Python object.
Authorization requirements:
Object-access permission to this storage group template.
Task permission to the “Configure Storage - System Programmer” task.
Storage Volume Templates
A StorageVolumeTemplate
object represents a
storage volume template for FCP or FICON (ECKD) that is defined in a
storage group template.
Storage volume template objects can be created, updated and deleted.
Storage volume templates are contained in storage group templates.
You can create as many storage volume templates as you want in a storage group template. When creating a storage group from the storage group template, each storage volume template will cause a storage volume to be created in the new storage group.
Storage group templates and storage volume templates only can be defined in CPCs that are in DPM mode and that have the “dpm-storage-management” feature enabled.
- class zhmcclient.StorageVolumeTemplateManager(storage_group_template)[source]
Manager providing access to the storage volume templates in a particular storage group template.
Derived from
BaseManager
; see there for common methods and attributes.Objects of this class are not directly created by the user; they are accessible via the following instance variable of a
StorageGroupTemplate
object:Attributes:
StorageGroupTemplate
: Storage group template defining the scope for this manager.class_name
The resource class name
parent
Subclass of
BaseResource
: Parent resource defining the scope for this manager.resource_class
The Python class of the parent resource of this manager.
session
Session
: Session with the HMC.Methods:
list
([full_properties, filter_args])List the storage volume templates in this storage group template.
create
(properties)Create a storage volume template in this storage group template on the HMC.
__repr__
()Return a string with the state of this manager object, for debug purposes.
find
(**filter_args)Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g.
find_by_name
(name)Find a resource by name (i.e.
find_local
(name, uri[, properties])Return a local resource object without fetching it from the HMC.
findall
(**filter_args)Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g.
flush
()Invalidate the Name-URI cache of this manager.
invalidate_cache
()Invalidate the Name-URI cache of this manager.
resource_object
(uri_or_oid[, props])Return a minimalistic Python resource object for this resource class, that is scoped to this manager.
- property storage_group_template
StorageGroupTemplate
: Storage group template defining the scope for this manager.
- list(full_properties=False, filter_args=None)[source]
List the storage volume templates in this storage group template.
Authorization requirements:
Object-access permission to this storage group template.
- Parameters
full_properties (bool) – Controls that the full set of resource properties for each returned storage volume template is being retrieved, vs. only the following short set: “element-uri”, “name”, “size”, and “usage”.
filter_args (dict) –
Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering.
None causes no filtering to happen, i.e. all resources are returned.
- Returns
A list of
StorageVolumeTemplate
objects.- Raises
- create(properties)[source]
Create a storage volume template in this storage group template on the HMC.
This method performs the “Modify Storage Template Properties” operation, requesting creation of the volume.
Authorization requirements:
Object-access permission to this storage group template.
Task permission to the “Configure Storage - System Programmer” task.
- Parameters
properties (dict) –
Initial property values for the new volume template.
Allowable properties are the fields defined in the “storage-template-volume-request-info” nested object described for operation “Modify Storage Template Properties” in the HMC API book. The valid fields are those for the “create” operation. The operation field must not be provided; it is set automatically to the value “create”.
The properties provided in this parameter will be copied and then amended with the operation=”create” field, and then used as a single array item for the storage-template-volumes field in the request body of the “Modify Storage Template Properties” operation.
- Returns
The resource object for the new storage volume template. The object will have the following properties set:
’element-uri’ as returned by the HMC
’element-id’ as determined from the ‘element-uri’ property
’class’ and ‘parent’
additional properties as specified in the input properties
- Return type
- Raises
Example:
stovol1 = fcp_stogrp.storage_volume_templates.create( properties=dict( name='vol1', size=30, # GiB ))
- class zhmcclient.StorageVolumeTemplate(manager, uri, name=None, properties=None)[source]
Representation of a storage volume template.
Derived from
BaseResource
; see there for common methods and attributes.Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case,
StorageVolumeTemplateManager
).Methods:
delete
()Delete this storage volume template on the HMC.
update_properties
(properties)Update writeable properties of this storage volume template on the HMC.
__repr__
()Return a string with the state of this resource, for debug purposes.
__str__
()Return a human readable string representation of this resource.
auto_update_enabled
()Return whether auto-update is currently enabled for the resource object.
disable_auto_update
()Disable auto-update for this resource object, if currently enabled.
enable_auto_update
()Enable auto-update for this resource object, if currently disabled.
get_properties_local
(names[, defaults])Return the values of a set of resource properties, using default values for those that are not present in this Python object, without retrieving them from the HMC.
get_property
(name)Return the value of a resource property.
prop
(name[, default])Return the value of a resource property, applying a default if it does not exist.
pull_full_properties
()Retrieve the full set of resource properties and cache them in this object.
update_properties_local
(properties)Update the values of a set of resource properties on this Python object without propagating the updates the HMC.
Attributes:
full_properties
A boolean indicating whether or not the resource properties in this object are the full set of resource properties.
manager
Subclass of
BaseManager
: Manager object for this resource (and for all resources of the same type in the scope of that manager).name
The name of the resource.
properties
The properties of this resource that are currently present in this Python object, as a dictionary.
properties_timestamp
The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).
uri
The canonical URI path of the resource.
- delete()[source]
Delete this storage volume template on the HMC.
This method performs the “Modify Storage Template Properties” operation, requesting deletion of the volume template.
Authorization requirements:
Object-access permission to the storage group template owning this storage volume template.
Task permission to the “Configure Storage - System Programmer” task.
- Raises
- update_properties(properties)[source]
Update writeable properties of this storage volume template on the HMC.
This method performs the “Modify Storage Template Properties” operation, requesting modification of the volume.
This method serializes with other methods that access or change properties on the same Python object.
Authorization requirements:
Object-access permission to the storage group template owning this storage volume template.
Task permission to the “Configure Storage - System Programmer” task.
- Parameters
properties (dict) –
New property values for the volume. Allowable properties are the fields defined in the “storage-template-volume-request-info” nested object for the “modify” operation. That nested object is described in operation “Modify Storage Template Properties” in the HMC API book.
The properties provided in this parameter will be copied and then amended with the operation=”modify” and element-uri properties, and then used as a single array item for the storage-template-volumes field in the request body of the “Modify Storage Template Properties” operation.
- Raises
Capacity Groups
A Capacity Group is a group of partitions that allows defining a capping for the total amount of physical processors consumed by the Partitions in the group. The Partitions must be defined with shared processors, and a Partition can be a member of at most one Capacity Group.
Capacity Group resources are contained in CPC resources.
Capacity Groups only exist in CPCs that are in DPM mode.
- class zhmcclient.CapacityGroupManager(cpc)[source]
Manager providing access to the Capacity Groups in a particular CPC.
Derived from
BaseManager
; see there for common methods and attributes.Objects of this class are not directly created by the user; they are accessible via the following instance variable of a
Cpc
object (in DPM mode):Attributes:
CPC defining the scope for this manager.
class_name
The resource class name
parent
Subclass of
BaseResource
: Parent resource defining the scope for this manager.resource_class
The Python class of the parent resource of this manager.
session
Session
: Session with the HMC.Methods:
list
([full_properties, filter_args])List the Capacity Groups in this CPC.
create
(properties)Create a Capacity Group in this CPC.
__repr__
()Return a string with the state of this manager object, for debug purposes.
find
(**filter_args)Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g.
find_by_name
(name)Find a resource by name (i.e.
find_local
(name, uri[, properties])Return a local resource object without fetching it from the HMC.
findall
(**filter_args)Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g.
flush
()Invalidate the Name-URI cache of this manager.
invalidate_cache
()Invalidate the Name-URI cache of this manager.
resource_object
(uri_or_oid[, props])Return a minimalistic Python resource object for this resource class, that is scoped to this manager.
- list(full_properties=False, filter_args=None)[source]
List the Capacity Groups in this CPC.
Authorization requirements:
Object-access permission to this CPC.
- Parameters
full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation.
filter_args (dict) –
Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering.
None causes no filtering to happen, i.e. all resources are returned.
- Returns
A list of
CapacityGroup
objects.- Raises
- create(properties)[source]
Create a Capacity Group in this CPC.
The new Capacity Group initially has no partitions.
Authorization requirements:
Object-access permission to this CPC.
Task permission to the “Manage Processor Sharing” task.
- Parameters
properties (dict) – Initial property values. Allowable properties are defined in section ‘Request body contents’ in section ‘Create Capacity Group’ in the HMC API book.
- Returns
The resource object for the new Capacity Group. The object will have its ‘element-uri’ property set as returned by the HMC, and will also have the input properties set.
- Return type
- Raises
- class zhmcclient.CapacityGroup(manager, uri, name=None, properties=None)[source]
Representation of a Capacity Group.
Derived from
BaseResource
; see there for common methods and attributes.For the properties of a Capacity Group resource, see section ‘Data model’ in section ‘Capacity Group element object’ in the HMC API book.
Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case,
CapacityGroupManager
).Methods:
delete
()Delete this Capacity Group.
update_properties
(properties)Update writeable properties of this Capacity Group.
add_partition
(partition)Add a Partition to this Capacity Group.
remove_partition
(partition)Remove a Partition from this Capacity Group.
__repr__
()Return a string with the state of this resource, for debug purposes.
__str__
()Return a human readable string representation of this resource.
auto_update_enabled
()Return whether auto-update is currently enabled for the resource object.
disable_auto_update
()Disable auto-update for this resource object, if currently enabled.
enable_auto_update
()Enable auto-update for this resource object, if currently disabled.
get_properties_local
(names[, defaults])Return the values of a set of resource properties, using default values for those that are not present in this Python object, without retrieving them from the HMC.
get_property
(name)Return the value of a resource property.
prop
(name[, default])Return the value of a resource property, applying a default if it does not exist.
pull_full_properties
()Retrieve the full set of resource properties and cache them in this object.
update_properties_local
(properties)Update the values of a set of resource properties on this Python object without propagating the updates the HMC.
Attributes:
full_properties
A boolean indicating whether or not the resource properties in this object are the full set of resource properties.
manager
Subclass of
BaseManager
: Manager object for this resource (and for all resources of the same type in the scope of that manager).name
The name of the resource.
properties
The properties of this resource that are currently present in this Python object, as a dictionary.
properties_timestamp
The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).
uri
The canonical URI path of the resource.
- delete()[source]
Delete this Capacity Group.
The Capacity Group must not contain any Partitions.
Authorization requirements:
Object-access permission to the CPC containing this Capacity Group.
Task permission to the “Manage Processor Sharing” task.
- Raises
- update_properties(properties)[source]
Update writeable properties of this Capacity Group.
This method serializes with other methods that access or change properties on the same Python object.
Authorization requirements:
Object-access permission to the CPC containing this Capacity Group.
Task permission to the “Manage Processor Sharing” task.
- add_partition(partition)[source]
Add a Partition to this Capacity Group.
Upon successful completion, the amount of processing capacity that could be used by this Partition becomes governed by the absolute cap values defined for this Capacity Group.
A Partition cannot become a member of more than one Capacity Group. The Partition must be defined with shared processors and the Capacity Group must specify nonzero cap values for the processor types used by the Partition. The Partition must be on the same CPC as the Capacity Group and must not yet be a member of this (or any other) Capacity Group.
Authorization requirements:
Object-access permission to the CPC containing this Capacity Group.
Task permission to the “Manage Processor Sharing” task.
- Parameters
partition (
Partition
) – The partition to be added.- Raises
- remove_partition(partition)[source]
Remove a Partition from this Capacity Group.
Upon successful completion, the amount of processing capacity that could be used by this Partition is no longer governed by the absolute cap values defined for this Capacity Group.
The Partition must be a member of this Capacity Group.
Authorization requirements:
Object-access permission to the CPC containing this Capacity Group.
Task permission to the “Manage Processor Sharing” task.
- Parameters
partition (
Partition
) – The partition to be removed.- Raises
Console
A Console resource represents an HMC.
In a paired setup with primary and alternate HMC, each HMC is represented as a separate Console resource.
- class zhmcclient.ConsoleManager(client)[source]
Manager providing access to the Console representing the HMC this client is connected to.
In a paired setup with primary and alternate HMC, each HMC is represented as a separate Console resource.
Derived from
BaseManager
; see there for common methods and attributes.Objects of this class are not directly created by the user; they are accessible via the following instance variable of a
Client
object:Attributes:
Client
: The client defining the scope for this manager.Console
: The Console representing the HMC this client is connected to.class_name
The resource class name
parent
Subclass of
BaseResource
: Parent resource defining the scope for this manager.resource_class
The Python class of the parent resource of this manager.
session
Session
: Session with the HMC.Methods:
list
([full_properties, filter_args])List the (one) Console representing the HMC this client is connected to.
__repr__
()Return a string with the state of this manager object, for debug purposes.
find
(**filter_args)Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g.
find_by_name
(name)Find a resource by name (i.e.
find_local
(name, uri[, properties])Return a local resource object without fetching it from the HMC.
findall
(**filter_args)Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g.
flush
()Invalidate the Name-URI cache of this manager.
invalidate_cache
()Invalidate the Name-URI cache of this manager.
resource_object
(uri_or_oid[, props])Return a minimalistic Python resource object for this resource class, that is scoped to this manager.
- property console
Console
: The Console representing the HMC this client is connected to.The returned object is cached, so it is looked up only upon first access to this property.
The returned object has only the following properties set:
‘class’
‘parent’
‘object-uri’
Use
get_property()
orprop()
to access any properties regardless of whether they are already set or first need to be retrieved.
- class zhmcclient.Console(manager, uri, name=None, properties=None)[source]
Representation of a Console.
Derived from
BaseResource
; see there for common methods and attributes.Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case,
ConsoleManager
).Attributes:
StorageGroupManager
: Manager object for the Storage Groups in scope of this Console.StorageGroupTemplateManager
: Manager object for the Storage Group Templates in scope of this Console.Access to the Users in this Console.
Access to the User Roles in this Console.
Access to the User Patterns in this Console.
Access to the Password Rules in this Console.
Access to the Tasks in this Console.
Access to the LDAP Server Definitions in this Console.
Access to the unmanaged CPCs in this Console.
full_properties
A boolean indicating whether or not the resource properties in this object are the full set of resource properties.
manager
Subclass of
BaseManager
: Manager object for this resource (and for all resources of the same type in the scope of that manager).name
The name of the resource.
properties
The properties of this resource that are currently present in this Python object, as a dictionary.
properties_timestamp
The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).
uri
The canonical URI path of the resource.
Methods:
restart
([force, wait_for_available, ...])Restart the HMC represented by this Console object.
shutdown
([force])Shut down and power off the HMC represented by this Console object.
Change the role of the alternate HMC represented by this Console object to become the primary HMC.
get_audit_log
([begin_time, end_time])Return the console audit log entries, optionally filtered by their creation time.
get_security_log
([begin_time, end_time])Return the console security log entries, optionally filtered by their creation time.
list_unmanaged_cpcs
([name])List the unmanaged CPCs of this HMC.
list_permitted_partitions
([full_properties, ...])List the permitted partitions of CPCs in DPM mode managed by this HMC.
list_permitted_lpars
([full_properties, ...])List the permitted LPARs of CPCs in classic mode managed by this HMC.
__repr__
()Return a string with the state of this resource, for debug purposes.
__str__
()Return a human readable string representation of this resource.
auto_update_enabled
()Return whether auto-update is currently enabled for the resource object.
disable_auto_update
()Disable auto-update for this resource object, if currently enabled.
enable_auto_update
()Enable auto-update for this resource object, if currently disabled.
get_properties_local
(names[, defaults])Return the values of a set of resource properties, using default values for those that are not present in this Python object, without retrieving them from the HMC.
get_property
(name)Return the value of a resource property.
prop
(name[, default])Return the value of a resource property, applying a default if it does not exist.
pull_full_properties
()Retrieve the full set of resource properties and cache them in this object.
update_properties_local
(properties)Update the values of a set of resource properties on this Python object without propagating the updates the HMC.
- property storage_groups
StorageGroupManager
: Manager object for the Storage Groups in scope of this Console.
- property storage_group_templates
StorageGroupTemplateManager
: Manager object for the Storage Group Templates in scope of this Console.
- property user_roles
Access to the User Roles in this Console.
- Type
- property user_patterns
Access to the User Patterns in this Console.
- Type
- property password_rules
Access to the Password Rules in this Console.
- Type
- property ldap_server_definitions
Access to the LDAP Server Definitions in this Console.
- restart(force=False, wait_for_available=True, operation_timeout=None)[source]
Restart the HMC represented by this Console object.
Once the HMC is online again, this Console object, as well as any other resource objects accessed through this HMC, can continue to be used. An automatic re-logon will be performed under the covers, because the HMC restart invalidates the currently used HMC session.
Authorization requirements:
Task permission for the “Shutdown/Restart” task.
“Remote Restart” must be enabled on the HMC.
- Parameters
force (bool) – Boolean controlling whether the restart operation is processed when users are connected (True) or not (False). Users in this sense are local or remote GUI users. HMC WS API clients do not count as users for this purpose.
wait_for_available (bool) –
Boolean controlling whether this method should wait for the HMC to become available again after the restart, as follows:
If True, this method will wait until the HMC has restarted and is available again. The
query_api_version()
method will be used to check for availability of the HMC.If False, this method will return immediately once the HMC has accepted the request to be restarted.
operation_timeout (number) – Timeout in seconds, for waiting for HMC availability after the restart. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_available=True, a
OperationTimeout
is raised.
- Raises
OperationTimeout – The timeout expired while waiting for the HMC to become available again after the restart.
- shutdown(force=False)[source]
Shut down and power off the HMC represented by this Console object.
While the HMC is powered off, any Python resource objects retrieved from this HMC may raise exceptions upon further use.
In order to continue using Python resource objects retrieved from this HMC, the HMC needs to be started again (e.g. by powering it on locally). Once the HMC is available again, Python resource objects retrieved from that HMC can continue to be used. An automatic re-logon will be performed under the covers, because the HMC startup invalidates the currently used HMC session.
Authorization requirements:
Task permission for the “Shutdown/Restart” task.
“Remote Shutdown” must be enabled on the HMC.
- Parameters
force (bool) – Boolean controlling whether the shutdown operation is processed when users are connected (True) or not (False). Users in this sense are local or remote GUI users. HMC WS API clients do not count as users for this purpose.
- Raises
- make_primary()[source]
Change the role of the alternate HMC represented by this Console object to become the primary HMC.
If that HMC is already the primary HMC, this method does not change its rols and succeeds.
The HMC represented by this Console object must participate in a {primary, alternate} pairing.
Authorization requirements:
Task permission for the “Manage Alternate HMC” task.
- Raises
- get_audit_log(begin_time=None, end_time=None)[source]
Return the console audit log entries, optionally filtered by their creation time.
Authorization requirements:
Task permission to the “Audit and Log Management” task.
- Parameters
begin_time (
datetime
) –Begin time for filtering. Log entries with a creation time older than the begin time will be omitted from the results.
If None, no such filtering is performed (and the oldest available log entries will be included).
end_time (
datetime
) –End time for filtering. Log entries with a creation time newer than the end time will be omitted from the results.
If None, no such filtering is performed (and the newest available log entries will be included).
- Returns
A JSON object with the log entries, as described in section ‘Response body contents’ of operation ‘Get Console Audit Log’ in the HMC API book.
- Return type
- Raises
- get_security_log(begin_time=None, end_time=None)[source]
Return the console security log entries, optionally filtered by their creation time.
Authorization requirements:
Task permission to the “View Security Logs” task.
- Parameters
begin_time (
datetime
) –Begin time for filtering. Log entries with a creation time older than the begin time will be omitted from the results.
If None, no such filtering is performed (and the oldest available log entries will be included).
end_time (
datetime
) –End time for filtering. Log entries with a creation time newer than the end time will be omitted from the results.
If None, no such filtering is performed (and the newest available log entries will be included).
- Returns
A JSON object with the log entries, as described in section ‘Response body contents’ of operation ‘Get Console Security Log’ in the HMC API book.
- Return type
- Raises
- list_unmanaged_cpcs(name=None)[source]
List the unmanaged CPCs of this HMC.
For details, see
list()
.Authorization requirements:
None
- Parameters
name (string) –
Regular expression pattern for the CPC name, as a filter that narrows the list of returned CPCs to those whose name property matches the specified pattern.
None causes no filtering to happen, i.e. all unmanaged CPCs discovered by the HMC are returned.
- Returns
A list of
UnmanagedCpc
objects.- Raises
- list_permitted_partitions(full_properties=False, filter_args=None)[source]
List the permitted partitions of CPCs in DPM mode managed by this HMC.
Added in version 1.0; requires HMC 2.14.0 or later and otherwise raises HTTPError(404.4).
Any CPCs in classic mode managed by the HMC will be ignored for this operation.
The partitions in the result can be additionally limited by specifying filter arguments.
Authorization requirements:
Object permission to the partition objects included in the result.
- Parameters
full_properties (bool) – Controls whether the full set of resource properties for the returned Partition objects should be retrieved, vs. only a short set.
filter_args (dict) –
Filter arguments for limiting the partitions in the result. None causes no filtering to happen.
The following filter arguments are supported by server-side filtering:
name (string): Limits the result to partitions whose name match the specified regular expression.
type (string): Limits the result to partitions with a matching “type” property value (i.e. “linux”, “ssc”, “zvm”).
status (string): Limits the result to partitions with a matching “status” property value.
has-unacceptable-status (bool): Limits the result to partitions with a matching “has-unacceptable-status” property value.
cpc-name (string): Limits the result to partitions whose CPC has a name that matches the specified regular expression.
Any other valid property of partitions is supported by client-side filtering:
<property-name>: Any other property of partitions.
- Returns
A list of
Partition
objects.- Raises
- list_permitted_lpars(full_properties=False, filter_args=None)[source]
List the permitted LPARs of CPCs in classic mode managed by this HMC.
Added in version 1.0; requires HMC 2.14.0 or later
Any CPCs in DPM mode managed by the HMC will be ignored for this operation.
The LPARs in the result can be additionally limited by specifying filter arguments.
Authorization requirements:
Object permission to the LPAR objects included in the result.
- Parameters
full_properties (bool) – Controls whether the full set of resource properties for the returned LPAR objects should be retrieved, vs. only a short set.
filter_args (dict) –
Filter arguments for limiting the LPARs in the result. None causes no filtering to happen.
The following filter arguments are supported by server-side filtering:
name (string): Limits the result to LPARs whose name match the specified regular expression.
activation-mode (string): Limits the result to LPARs with a matching “activation-mode” property value.
status (string): Limits the result to LPARs with a matching “status” property value.
has-unacceptable-status (bool): Limits the result to LPARs with a matching “has-unacceptable-status” property value.
cpc-name (string): Limits the result to LPARs whose CPC has a name that matches the specified regular expression.
Any other valid property of LPARs is supported by client-side filtering:
<property-name>: Any other property of LPARs.
- Returns
A list of
Lpar
objects.- Raises
User
A User resource represents a user configured in the HMC.
- class zhmcclient.UserManager(console)[source]
Manager providing access to the User resources of a HMC.
Derived from
BaseManager
; see there for common methods and attributes.Objects of this class are not directly created by the user; they are accessible via the following instance variable of a
Console
object:Attributes:
Console defining the scope for this manager.
class_name
The resource class name
parent
Subclass of
BaseResource
: Parent resource defining the scope for this manager.resource_class
The Python class of the parent resource of this manager.
session
Session
: Session with the HMC.Methods:
list
([full_properties, filter_args])List the User resources representing the users defined in this HMC.
create
(properties)Create a new User in this HMC.
__repr__
()Return a string with the state of this manager object, for debug purposes.
find
(**filter_args)Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g.
find_by_name
(name)Find a resource by name (i.e.
find_local
(name, uri[, properties])Return a local resource object without fetching it from the HMC.
findall
(**filter_args)Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g.
flush
()Invalidate the Name-URI cache of this manager.
invalidate_cache
()Invalidate the Name-URI cache of this manager.
resource_object
(uri_or_oid[, props])Return a minimalistic Python resource object for this resource class, that is scoped to this manager.
- list(full_properties=True, filter_args=None)[source]
List the User resources representing the users defined in this HMC.
Authorization requirements:
User-related-access permission to the User object included in the result, or, depending on the type of User object, task permission to the “Manage Users” task or the “Manage User Templates” task.
- Parameters
full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation.
filter_args (dict) –
Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering.
None causes no filtering to happen, i.e. all resources are returned.
- Returns
A list of
User
objects.- Raises
- create(properties)[source]
Create a new User in this HMC.
Authorization requirements:
Task permission to the “Manage Users” task to create a standard user or the “Manage User Templates” task to create a template user.
- Parameters
properties (dict) – Initial property values. Allowable properties are defined in section ‘Request body contents’ in section ‘Create User’ in the HMC API book.
- Returns
The resource object for the new User. The object will have its ‘object-uri’ property set as returned by the HMC, and will also have the input properties set.
- Return type
- Raises
- class zhmcclient.User(manager, uri, name=None, properties=None)[source]
Representation of a User.
Derived from
BaseResource
; see there for common methods and attributes.Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case,
UserManager
).Methods:
delete
()Delete this User.
update_properties
(properties)Update writeable properties of this User.
add_user_role
(user_role)Add the specified User Role to this User.
remove_user_role
(user_role)Remove the specified User Role from this User.
__repr__
()Return a string with the state of this resource, for debug purposes.
__str__
()Return a human readable string representation of this resource.
auto_update_enabled
()Return whether auto-update is currently enabled for the resource object.
disable_auto_update
()Disable auto-update for this resource object, if currently enabled.
enable_auto_update
()Enable auto-update for this resource object, if currently disabled.
get_properties_local
(names[, defaults])Return the values of a set of resource properties, using default values for those that are not present in this Python object, without retrieving them from the HMC.
get_property
(name)Return the value of a resource property.
prop
(name[, default])Return the value of a resource property, applying a default if it does not exist.
pull_full_properties
()Retrieve the full set of resource properties and cache them in this object.
update_properties_local
(properties)Update the values of a set of resource properties on this Python object without propagating the updates the HMC.
Attributes:
full_properties
A boolean indicating whether or not the resource properties in this object are the full set of resource properties.
manager
Subclass of
BaseManager
: Manager object for this resource (and for all resources of the same type in the scope of that manager).name
The name of the resource.
properties
The properties of this resource that are currently present in this Python object, as a dictionary.
properties_timestamp
The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).
uri
The canonical URI path of the resource.
- delete()[source]
Delete this User.
Authorization requirements:
Task permission to the “Manage Users” task to delete a non-template user, or the “Manage User Templates” task to delete a template user.
- Raises
- update_properties(properties)[source]
Update writeable properties of this User.
This method serializes with other methods that access or change properties on the same Python object.
Authorization requirements:
Task permission to the “Manage Users” task to update a non-template user, or the “Manage User Templates” task to update a template user.
For a user to update their own password or default-group-uri property, user-related-access permission to the user represented by this User object, or task permission to the “Manage Users” task is required.
- add_user_role(user_role)[source]
Add the specified User Role to this User.
This User must not be a system-defined or pattern-based user.
Authorization requirements:
Task permission to the “Manage Users” task to modify a standard user or the “Manage User Templates” task to modify a template user.
- Parameters
user_role (
UserRole
) – User Role to be added. Must not be None.- Raises
- remove_user_role(user_role)[source]
Remove the specified User Role from this User.
This User must not be a system-defined or pattern-based user.
Authorization requirements:
Task permission to the “Manage Users” task to modify a standard user or the “Manage User Templates” task to modify a template user.
- Parameters
user_role (
UserRole
) – User Role to be removed. Must not be None.- Raises
User Role
A User Role resource represents an authority role which can be assigned to one or more HMC users.
A User Role may allow access to specific managed objects, classes of managed objects, groups and/or tasks. There are two types of User Roles: user-defined and system-defined. User-defined User Roles are created by an HMC user, whereas the system-defined User Roles are pre-defined, standard User Roles supplied with the HMC.
- class zhmcclient.UserRoleManager(console)[source]
Manager providing access to the User Role resources of a HMC.
Derived from
BaseManager
; see there for common methods and attributes.Objects of this class are not directly created by the user; they are accessible via the following instance variable of a
Console
object:Attributes:
Console defining the scope for this manager.
class_name
The resource class name
parent
Subclass of
BaseResource
: Parent resource defining the scope for this manager.resource_class
The Python class of the parent resource of this manager.
session
Session
: Session with the HMC.Methods:
list
([full_properties, filter_args])List the User Role resources representing the user roles defined in this HMC.
create
(properties)Create a new (user-defined) User Role in this HMC.
__repr__
()Return a string with the state of this manager object, for debug purposes.
find
(**filter_args)Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g.
find_by_name
(name)Find a resource by name (i.e.
find_local
(name, uri[, properties])Return a local resource object without fetching it from the HMC.
findall
(**filter_args)Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g.
flush
()Invalidate the Name-URI cache of this manager.
invalidate_cache
()Invalidate the Name-URI cache of this manager.
resource_object
(uri_or_oid[, props])Return a minimalistic Python resource object for this resource class, that is scoped to this manager.
- list(full_properties=True, filter_args=None)[source]
List the User Role resources representing the user roles defined in this HMC.
Authorization requirements:
User-related-access permission to the User Role objects included in the result, or task permission to the “Manage User Roles” task.
- Parameters
full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation.
filter_args (dict) –
Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering.
None causes no filtering to happen, i.e. all resources are returned.
- Returns
A list of
UserRole
objects.- Raises
- create(properties)[source]
Create a new (user-defined) User Role in this HMC.
Authorization requirements:
Task permission to the “Manage User Roles” task.
- Parameters
properties (dict) – Initial property values. Allowable properties are defined in section ‘Request body contents’ in section ‘Create User Role’ in the HMC API book.
- Returns
The resource object for the new User Role. The object will have its ‘object-uri’ property set as returned by the HMC, and will also have the input properties set.
- Return type
- Raises
- class zhmcclient.UserRole(manager, uri, name=None, properties=None)[source]
Representation of a User Role.
Derived from
BaseResource
; see there for common methods and attributes.Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case,
UserRoleManager
).Methods:
delete
()Delete this User Role.
update_properties
(properties)Update writeable properties of this User Role.
add_permission
(permitted_object[, ...])Add permission for the specified permitted object(s) to this User Role, thereby granting that permission to all users that have this User Role.
remove_permission
(permitted_object[, ...])Remove permission for the specified permitted object(s) from this User Role, thereby no longer granting that permission to all users that have this User Role.
__repr__
()Return a string with the state of this resource, for debug purposes.
__str__
()Return a human readable string representation of this resource.
auto_update_enabled
()Return whether auto-update is currently enabled for the resource object.
disable_auto_update
()Disable auto-update for this resource object, if currently enabled.
enable_auto_update
()Enable auto-update for this resource object, if currently disabled.
get_properties_local
(names[, defaults])Return the values of a set of resource properties, using default values for those that are not present in this Python object, without retrieving them from the HMC.
get_property
(name)Return the value of a resource property.
prop
(name[, default])Return the value of a resource property, applying a default if it does not exist.
pull_full_properties
()Retrieve the full set of resource properties and cache them in this object.
update_properties_local
(properties)Update the values of a set of resource properties on this Python object without propagating the updates the HMC.
Attributes:
full_properties
A boolean indicating whether or not the resource properties in this object are the full set of resource properties.
manager
Subclass of
BaseManager
: Manager object for this resource (and for all resources of the same type in the scope of that manager).name
The name of the resource.
properties
The properties of this resource that are currently present in this Python object, as a dictionary.
properties_timestamp
The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).
uri
The canonical URI path of the resource.
- delete()[source]
Delete this User Role.
The User Role must be user-defined. System-defined User Roles cannot be deleted.
Authorization requirements:
Task permission to the “Manage User Roles” task.
- Raises
- update_properties(properties)[source]
Update writeable properties of this User Role.
The User Role must be user-defined. System-defined User Roles cannot be updated.
This method serializes with other methods that access or change properties on the same Python object.
Authorization requirements:
Task permission to the “Manage User Roles” task.
- add_permission(permitted_object, include_members=False, view_only=True)[source]
Add permission for the specified permitted object(s) to this User Role, thereby granting that permission to all users that have this User Role.
The granted permission depends on the resource class of the permitted object(s):
For Task resources, the granted permission is task permission for that task.
For Group resources, the granted permission is object access permission for the group resource, and optionally also for the group members.
For any other resources, the granted permission is object access permission for these resources.
The User Role must be user-defined.
Authorization requirements:
Task permission to the “Manage User Roles” task.
- Parameters
permitted_object (
BaseResource
or string) –Permitted object(s), either as a Python resource object (e.g.
Partition
), or as a resource class string (e.g. ‘partition’).Must not be None.
include_members (bool) –
Controls whether for Group resources, the operation applies additionally to its group member resources.
This parameter will be ignored when the permitted object does not specify Group resources.
view_only (bool) –
Controls whether for Task resources, the operation aplies to the view-only version of the task (if True), or to the full version of the task (if False). Only certain tasks support a view-only version.
This parameter will be ignored when the permitted object does not specify Task resources.
- Raises
- remove_permission(permitted_object, include_members=False, view_only=True)[source]
Remove permission for the specified permitted object(s) from this User Role, thereby no longer granting that permission to all users that have this User Role.
The granted permission depends on the resource class of the permitted object(s):
For Task resources, the granted permission is task permission for that task.
For Group resources, the granted permission is object access permission for the group resource, and optionally also for the group members.
For any other resources, the granted permission is object access permission for these resources.
The User Role must be user-defined.
Authorization requirements:
Task permission to the “Manage User Roles” task.
- Parameters
permitted_object (
BaseResource
or string) –Permitted object(s), either as a Python resource object (e.g.
Partition
), or as a resource class string (e.g. ‘partition’).Must not be None.
include_members (bool) –
Controls whether for Group resources, the operation applies additionally to its group member resources.
This parameter will be ignored when the permitted object does not specify Group resources.
view_only (bool) –
Controls whether for Task resources, the operation aplies to the view-only version of the task (if True), or to the full version of the task (if False). Only certain tasks support a view-only version.
This parameter will be ignored when the permitted object does not specify Task resources.
- Raises
User Pattern
A User Pattern resource represents a pattern for HMC user IDs that are not defined on the HMC but can be verified by an LDAP server for user authentication.
User Patterns and user templates allow a system administrator to define a group of HMC users at once whose user IDs all match a certain pattern (for example, a regular expression) and who have a certain set of attributes. Each pattern identifies a template User object which defines many characteristics of such users. A successful logon with a user ID that matches a User Pattern results in the creation of a pattern-based user, with many of its attributes coming from the associated template.
User Patterns are searched in a defined order during logon processing. That
order can be customized through the
reorder()
method.
- class zhmcclient.UserPatternManager(console)[source]
Manager providing access to the User Pattern resources of a HMC.
Derived from
BaseManager
; see there for common methods and attributes.Objects of this class are not directly created by the user; they are accessible via the following instance variable of a
Console
object:Attributes:
Console defining the scope for this manager.
class_name
The resource class name
parent
Subclass of
BaseResource
: Parent resource defining the scope for this manager.resource_class
The Python class of the parent resource of this manager.
session
Session
: Session with the HMC.Methods:
list
([full_properties, filter_args])List the User Pattern resources representing the user patterns defined in this HMC.
create
(properties)Create a new User Pattern in this HMC.
reorder
(user_patterns)Reorder the User Patterns of the HMC as specified.
__repr__
()Return a string with the state of this manager object, for debug purposes.
find
(**filter_args)Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g.
find_by_name
(name)Find a resource by name (i.e.
find_local
(name, uri[, properties])Return a local resource object without fetching it from the HMC.
findall
(**filter_args)Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g.
flush
()Invalidate the Name-URI cache of this manager.
invalidate_cache
()Invalidate the Name-URI cache of this manager.
resource_object
(uri_or_oid[, props])Return a minimalistic Python resource object for this resource class, that is scoped to this manager.
- list(full_properties=True, filter_args=None)[source]
List the User Pattern resources representing the user patterns defined in this HMC.
Authorization requirements:
User-related-access permission to the User Pattern objects included in the result, or task permission to the “Manage User Patterns” task.
- Parameters
full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation.
filter_args (dict) –
Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering.
None causes no filtering to happen, i.e. all resources are returned.
- Returns
A list of
UserPattern
objects.- Raises
- create(properties)[source]
Create a new User Pattern in this HMC.
Authorization requirements:
Task permission to the “Manage User Patterns” task.
- Parameters
properties (dict) – Initial property values. Allowable properties are defined in section ‘Request body contents’ in section ‘Create User Pattern’ in the HMC API book.
- Returns
The resource object for the new User Pattern. The object will have its ‘element-uri’ property set as returned by the HMC, and will also have the input properties set.
- Return type
- Raises
- reorder(user_patterns)[source]
Reorder the User Patterns of the HMC as specified.
The order of User Patterns determines the search order during logon processing.
Authorization requirements:
Task permission to the “Manage User Patterns” task.
- Parameters
user_patterns (list of
UserPattern
) –The User Patterns in the desired order.
Must not be None.
- Raises
- class zhmcclient.UserPattern(manager, uri, name=None, properties=None)[source]
Representation of a User Pattern.
Derived from
BaseResource
; see there for common methods and attributes.Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case,
UserPatternManager
).Methods:
delete
()Delete this User Pattern.
update_properties
(properties)Update writeable properties of this UserPattern.
__repr__
()Return a string with the state of this resource, for debug purposes.
__str__
()Return a human readable string representation of this resource.
auto_update_enabled
()Return whether auto-update is currently enabled for the resource object.
disable_auto_update
()Disable auto-update for this resource object, if currently enabled.
enable_auto_update
()Enable auto-update for this resource object, if currently disabled.
get_properties_local
(names[, defaults])Return the values of a set of resource properties, using default values for those that are not present in this Python object, without retrieving them from the HMC.
get_property
(name)Return the value of a resource property.
prop
(name[, default])Return the value of a resource property, applying a default if it does not exist.
pull_full_properties
()Retrieve the full set of resource properties and cache them in this object.
update_properties_local
(properties)Update the values of a set of resource properties on this Python object without propagating the updates the HMC.
Attributes:
full_properties
A boolean indicating whether or not the resource properties in this object are the full set of resource properties.
manager
Subclass of
BaseManager
: Manager object for this resource (and for all resources of the same type in the scope of that manager).name
The name of the resource.
properties
The properties of this resource that are currently present in this Python object, as a dictionary.
properties_timestamp
The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).
uri
The canonical URI path of the resource.
- delete()[source]
Delete this User Pattern.
Authorization requirements:
Task permission to the “Manage User Patterns” task.
- Raises
- update_properties(properties)[source]
Update writeable properties of this UserPattern.
This method serializes with other methods that access or change properties on the same Python object.
Authorization requirements:
Task permission to the “Manage User Patterns” task.
Password Rule
A Password Rule resource represents a rule which an HMC user must follow when creating a HMC logon password. Each HMC user using local authentication (i.e. not LDAP) is assigned a password rule. There are certain system-defined password rules available for use.
- class zhmcclient.PasswordRuleManager(console)[source]
Manager providing access to the Password Rule resources of a HMC.
Derived from
BaseManager
; see there for common methods and attributes.Objects of this class are not directly created by the user; they are accessible via the following instance variable of a
Console
object:Attributes:
Console defining the scope for this manager.
class_name
The resource class name
parent
Subclass of
BaseResource
: Parent resource defining the scope for this manager.resource_class
The Python class of the parent resource of this manager.
session
Session
: Session with the HMC.Methods:
list
([full_properties, filter_args])List the Password Rule resources representing the password rules defined in this HMC.
create
(properties)Create a new Password Rule in this HMC.
__repr__
()Return a string with the state of this manager object, for debug purposes.
find
(**filter_args)Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g.
find_by_name
(name)Find a resource by name (i.e.
find_local
(name, uri[, properties])Return a local resource object without fetching it from the HMC.
findall
(**filter_args)Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g.
flush
()Invalidate the Name-URI cache of this manager.
invalidate_cache
()Invalidate the Name-URI cache of this manager.
resource_object
(uri_or_oid[, props])Return a minimalistic Python resource object for this resource class, that is scoped to this manager.
- list(full_properties=True, filter_args=None)[source]
List the Password Rule resources representing the password rules defined in this HMC.
Authorization requirements:
User-related-access permission to the Password Rule objects included in the result, or task permission to the “Manage Password Rules” task.
- Parameters
full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation.
filter_args (dict) –
Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering.
None causes no filtering to happen, i.e. all resources are returned.
- Returns
A list of
PasswordRule
objects.- Raises
- create(properties)[source]
Create a new Password Rule in this HMC.
Authorization requirements:
Task permission to the “Manage Password Rules” task.
- Parameters
properties (dict) – Initial property values. Allowable properties are defined in section ‘Request body contents’ in section ‘Create Password Rule’ in the HMC API book.
- Returns
The resource object for the new Password Rule. The object will have its ‘element-uri’ property set as returned by the HMC, and will also have the input properties set.
- Return type
- Raises
- class zhmcclient.PasswordRule(manager, uri, name=None, properties=None)[source]
Representation of a Password Rule.
Derived from
BaseResource
; see there for common methods and attributes.Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case,
PasswordRuleManager
).Methods:
delete
()Delete this Password Rule.
update_properties
(properties)Update writeable properties of this PasswordRule.
__repr__
()Return a string with the state of this resource, for debug purposes.
__str__
()Return a human readable string representation of this resource.
auto_update_enabled
()Return whether auto-update is currently enabled for the resource object.
disable_auto_update
()Disable auto-update for this resource object, if currently enabled.
enable_auto_update
()Enable auto-update for this resource object, if currently disabled.
get_properties_local
(names[, defaults])Return the values of a set of resource properties, using default values for those that are not present in this Python object, without retrieving them from the HMC.
get_property
(name)Return the value of a resource property.
prop
(name[, default])Return the value of a resource property, applying a default if it does not exist.
pull_full_properties
()Retrieve the full set of resource properties and cache them in this object.
update_properties_local
(properties)Update the values of a set of resource properties on this Python object without propagating the updates the HMC.
Attributes:
full_properties
A boolean indicating whether or not the resource properties in this object are the full set of resource properties.
manager
Subclass of
BaseManager
: Manager object for this resource (and for all resources of the same type in the scope of that manager).name
The name of the resource.
properties
The properties of this resource that are currently present in this Python object, as a dictionary.
properties_timestamp
The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).
uri
The canonical URI path of the resource.
- delete()[source]
Delete this Password Rule.
The Password Rule must be user-defined. System-defined Password Rules cannot be deleted.
Authorization requirements:
Task permission to the “Manage Password Rules” task.
- Raises
- update_properties(properties)[source]
Update writeable properties of this PasswordRule.
The Password Rule must be user-defined. System-defined Password Rules cannot be updated.
This method serializes with other methods that access or change properties on the same Python object.
Authorization requirements:
Task permission to the “Manage Password Rules” task.
Task
A Task resource represents an action that an HMC user with appropriate authority can perform. These actions could be available via the HMC’s graphical user interface, the Web Services APIs or both.
Tasks are predefined by the HMC and cannot be created, modified or deleted.
- class zhmcclient.TaskManager(console)[source]
Manager providing access to the Task resources of a HMC.
Derived from
BaseManager
; see there for common methods and attributes.Objects of this class are not directly created by the user; they are accessible via the following instance variable of a
Console
object:Attributes:
Console defining the scope for this manager.
class_name
The resource class name
parent
Subclass of
BaseResource
: Parent resource defining the scope for this manager.resource_class
The Python class of the parent resource of this manager.
session
Session
: Session with the HMC.Methods:
list
([full_properties, filter_args])List the Task resources representing the tasks defined in this HMC.
__repr__
()Return a string with the state of this manager object, for debug purposes.
find
(**filter_args)Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g.
find_by_name
(name)Find a resource by name (i.e.
find_local
(name, uri[, properties])Return a local resource object without fetching it from the HMC.
findall
(**filter_args)Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g.
flush
()Invalidate the Name-URI cache of this manager.
invalidate_cache
()Invalidate the Name-URI cache of this manager.
resource_object
(uri_or_oid[, props])Return a minimalistic Python resource object for this resource class, that is scoped to this manager.
- list(full_properties=True, filter_args=None)[source]
List the Task resources representing the tasks defined in this HMC.
Authorization requirements:
None
- Parameters
full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation.
filter_args (dict) –
Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering.
None causes no filtering to happen, i.e. all resources are returned.
- Returns
A list of
Task
objects.- Raises
- class zhmcclient.Task(manager, uri, name=None, properties=None)[source]
Representation of a Task.
Derived from
BaseResource
; see there for common methods and attributes.Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case,
TaskManager
).Methods:
__repr__
()Return a string with the state of this resource, for debug purposes.
__str__
()Return a human readable string representation of this resource.
auto_update_enabled
()Return whether auto-update is currently enabled for the resource object.
disable_auto_update
()Disable auto-update for this resource object, if currently enabled.
enable_auto_update
()Enable auto-update for this resource object, if currently disabled.
get_properties_local
(names[, defaults])Return the values of a set of resource properties, using default values for those that are not present in this Python object, without retrieving them from the HMC.
get_property
(name)Return the value of a resource property.
prop
(name[, default])Return the value of a resource property, applying a default if it does not exist.
pull_full_properties
()Retrieve the full set of resource properties and cache them in this object.
update_properties_local
(properties)Update the values of a set of resource properties on this Python object without propagating the updates the HMC.
Attributes:
full_properties
A boolean indicating whether or not the resource properties in this object are the full set of resource properties.
manager
Subclass of
BaseManager
: Manager object for this resource (and for all resources of the same type in the scope of that manager).name
The name of the resource.
properties
The properties of this resource that are currently present in this Python object, as a dictionary.
properties_timestamp
The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).
uri
The canonical URI path of the resource.
LDAP Server Definition
A LDAP Server Definition resource represents a definition that contains information about an LDAP server that may be used for HMC user authentication purposes.
- class zhmcclient.LdapServerDefinitionManager(console)[source]
Manager providing access to the LDAP Server Definition resources of a HMC.
Derived from
BaseManager
; see there for common methods and attributes.Objects of this class are not directly created by the user; they are accessible via the following instance variable of a
Console
object:Attributes:
Console defining the scope for this manager.
class_name
The resource class name
parent
Subclass of
BaseResource
: Parent resource defining the scope for this manager.resource_class
The Python class of the parent resource of this manager.
session
Session
: Session with the HMC.Methods:
list
([full_properties, filter_args])List the LDAP Server Definition resources representing the definitions of LDAp servers in this HMC.
create
(properties)Create a new LDAP Server Definition in this HMC.
__repr__
()Return a string with the state of this manager object, for debug purposes.
find
(**filter_args)Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g.
find_by_name
(name)Find a resource by name (i.e.
find_local
(name, uri[, properties])Return a local resource object without fetching it from the HMC.
findall
(**filter_args)Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g.
flush
()Invalidate the Name-URI cache of this manager.
invalidate_cache
()Invalidate the Name-URI cache of this manager.
resource_object
(uri_or_oid[, props])Return a minimalistic Python resource object for this resource class, that is scoped to this manager.
- list(full_properties=True, filter_args=None)[source]
List the LDAP Server Definition resources representing the definitions of LDAp servers in this HMC.
Authorization requirements:
User-related-access permission to the LDAP Server Definition objects included in the result, or task permission to the “Manage LDAP Server Definitions” task.
- Parameters
full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation.
filter_args (dict) –
Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering.
None causes no filtering to happen, i.e. all resources are returned.
- Returns
A list of
LdapServerDefinition
objects.- Raises
- create(properties)[source]
Create a new LDAP Server Definition in this HMC.
Authorization requirements:
Task permission to the “Manage LDAP Server Definitions” task.
- Parameters
properties (dict) – Initial property values. Allowable properties are defined in section ‘Request body contents’ in section ‘Create LDAP Server Definition’ in the HMC API book.
- Returns
The resource object for the new LDAP Server Definition. The object will have its ‘object-uri’ property set as returned by the HMC, and will also have the input properties set.
- Return type
- Raises
- class zhmcclient.LdapServerDefinition(manager, uri, name=None, properties=None)[source]
Representation of a LDAP Server Definition.
Derived from
BaseResource
; see there for common methods and attributes.Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case,
LdapServerDefinitionManager
).Methods:
delete
()Delete this LDAP Server Definition.
update_properties
(properties)Update writeable properties of this LDAP Server Definitions.
__repr__
()Return a string with the state of this resource, for debug purposes.
__str__
()Return a human readable string representation of this resource.
auto_update_enabled
()Return whether auto-update is currently enabled for the resource object.
disable_auto_update
()Disable auto-update for this resource object, if currently enabled.
enable_auto_update
()Enable auto-update for this resource object, if currently disabled.
get_properties_local
(names[, defaults])Return the values of a set of resource properties, using default values for those that are not present in this Python object, without retrieving them from the HMC.
get_property
(name)Return the value of a resource property.
prop
(name[, default])Return the value of a resource property, applying a default if it does not exist.
pull_full_properties
()Retrieve the full set of resource properties and cache them in this object.
update_properties_local
(properties)Update the values of a set of resource properties on this Python object without propagating the updates the HMC.
Attributes:
full_properties
A boolean indicating whether or not the resource properties in this object are the full set of resource properties.
manager
Subclass of
BaseManager
: Manager object for this resource (and for all resources of the same type in the scope of that manager).name
The name of the resource.
properties
The properties of this resource that are currently present in this Python object, as a dictionary.
properties_timestamp
The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).
uri
The canonical URI path of the resource.
- delete()[source]
Delete this LDAP Server Definition.
Authorization requirements:
Task permission to the “Manage LDAP Server Definitions” task.
- Raises
- update_properties(properties)[source]
Update writeable properties of this LDAP Server Definitions.
This method serializes with other methods that access or change properties on the same Python object.
Authorization requirements:
Task permission to the “Manage LDAP Server Definitions” task.
Notifications
The HMC supports the publishing of notifications for specific topics. This includes for example asynchronous job completion, property or status changes, and operating system messages issued in an LPAR or DPM partition.
The zhmcclient package supports receiving HMC notifications in an easy-to-use way, as shown in the following example that receives and displays OS messages for a DPM partition:
import zhmcclient
hmc = ...
userid = ...
password = ...
session = zhmcclient.Session(hmc, userid, password)
client = zhmcclient.Client(session)
cpc = client.cpcs.find(name=cpcname)
partition = cpc.partitions.find(name=partname)
topic = partition.open_os_message_channel(include_refresh_messages=True)
print("Subscribing for OS messages for partition %s on CPC %s using "
"notifications..." % (partition.name, cpc.name))
receiver = zhmcclient.NotificationReceiver(topic, hmc, userid, password)
try:
for headers, message in receiver.notifications():
print("HMC notification #%s:" % headers['session-sequence-nr'])
os_msg_list = message['os-messages']
for os_msg in os_msg_list:
msg_txt = os_msg['message-text'].strip('\n')
msg_id = os_msg['message-id']
print("OS message #%s:\n%s" % (msg_id, msg_txt))
except zhmcclient.NotificationError as exc:
print("Notification Error: {}".format(exc))
except KeyboardInterrupt:
print("Keyboard Interrupt - Leaving notification receiver loop...")
finally:
print("Closing notification receiver...")
receiver.close()
When running this example code in one terminal, and stopping or starting
the partition in another terminal, one can monitor the shutdown or boot
messages issued by the operating system. The following commands use the
zhmc
CLI provided in the zhmccli project to do that:
$ zhmc partition stop {cpc-name} {partition-name}
$ zhmc partition start {cpc-name} {partition-name}
- class zhmcclient.NotificationReceiver(topic_names, host, userid, password, port=61612)[source]
A class for receiving HMC notifications that are published to particular HMC notification topics.
Experimental: This class is considered experimental at this point, and its API may change incompatibly as long as it is experimental.
Creating an object of this class establishes a JMS session with the HMC and subscribes for the specified HMC notification topic(s).
Notification topic strings are created by the HMC in context of a particular client session (i.e.
Session
object). However, these topic strings can be used by any JMS message listener that knows the topic string and that authenticates under some valid HMC userid. The HMC userid used by the JMS listener does not need to be the one that was used for the client session in which the notification topic was originally created.- Parameters
topic_names (string or list/tuple thereof) – Name(s) of the HMC notification topic(s). Must not be None.
host (string) – HMC host. For valid formats, see the
host
property. Must not be None.userid (string) – Userid of the HMC user to be used. Must not be None.
password (string) – Password of the HMC user to be used. Must not be None.
port (integer) – STOMP TCP port. Defaults to
DEFAULT_STOMP_PORT
.
- notifications()[source]
Generator method that yields all HMC notifications (= JMS messages) received by this notification receiver.
Example:
desired_topic_types = ('security-notification', 'audit-notification') topics = session.get_notification_topics() topic_names = [t['topic-name'] for t in topics if t['topic-type'] in desired_topic_types] receiver = zhmcclient.NotificationReceiver( topic_names, hmc, userid, password) for headers, message in receiver.notifications(): . . . # processing of topic-specific message format
- Yields
A tuple (headers, message) representing one HMC notification, with:
headers (dict): The notification header fields.
Some important header fields (dict items) are:
‘notification-type’ (string): The HMC notification type (e.g. ‘os-message’, ‘job-completion’, or others).
‘session-sequence-nr’ (string): The sequence number of this HMC notification within the session created by this notification receiver object. This number starts at 0 when this receiver object is created, and is incremented each time an HMC notification is published to this receiver.
‘class’ (string): The class name of the HMC resource publishing the HMC notification (e.g. ‘partition’).
‘object-id’ (string) or ‘element-id’ (string): The ID of the HMC resource publishing the HMC notification.
For a complete list of notification header fields, see section “Message format” in chapter 4. “Asynchronous notification” in the HMC API book.
message (JSON object): Body of the HMC notification, converted into a JSON object.
The properties of the JSON object vary by notification type.
For a description of the JSON properties, see the sub-sections for each notification type within section “Notification message formats” in chapter 4. “Asynchronous notification” in the HMC API book.
- Raises
NotificationJMSError – Received JMS error from the HMC.
NotificationParseError – Cannot parse JMS message body as JSON.
- close()[source]
Disconnect and close the JMS session with the HMC.
This implicitly unsubscribes from the notification topic this receiver was created for, and causes the
notifications()
method to stop its iterations.
Mock support
The zhmcclient PyPI package provides unit testing support for its users via its
zhmcclient_mock
Python package. That package allows users of zhmcclient to
easily define a faked HMC that is populated with resources as needed by the
test case.
The faked HMC environment is set up by creating an instance of the
zhmcclient_mock.FakedSession
class instead of the
zhmcclient.Session
class:
import zhmcclient
import zhmcclient_mock
session = zhmcclient_mock.FakedSession('fake-host', 'fake-hmc', '2.13.1',
'1.8')
client = zhmcclient.Client(session)
cpcs = client.cpcs.list()
. . .
Other than using a different session class, the code operates against the same
zhmcclient API as before. For example, you can see in the example above that
the client object is set up from the same zhmcclient.Client
class as
before, and that the CPCs can be listed through the API of the client object as
before.
The difference is that the faked session object contains a faked HMC and does not communicate at all with an actual HMC.
The faked HMC of the faked session object can be accessed via the
hmc
attribute of the faked session object
in order to populate it with resources, for example to build up an initial
resource environment for a test case.
The following example of a unit test case shows how an initial set of resources
that is defined as a dictionary and loaded into the faked HMC using the
add_resources()
method:
import unittest
import zhmcclient
import zhmcclient_mock
class MyTests(unittest.TestCase):
def setUp(self):
self.session = zhmcclient_mock.FakedSession(
'fake-host', 'fake-hmc', '2.13.1', '1.8')
self.session.hmc.add_resources({
'cpcs': [
{
'properties': {
'name': 'cpc_1',
'description': 'CPC #1',
},
'adapters': [
{
'properties': {
'name': 'osa_1',
'description': 'OSA #1',
'adapter-family': 'osa',
},
'ports': [
{
'properties': {
'name': 'osa_1_1',
'description': 'OSA #1 Port #1',
},
},
]
},
]
},
]
})
self.client = zhmcclient.Client(self.session)
def test_list(self):
cpcs = self.client.cpcs.list()
self.assertEqual(len(cpcs), 1)
self.assertEqual(cpcs[0].name, 'cpc_1')
In this example, the test_list()
method tests the CPC list method of the
zhmcclient package, but the same approach is used for testing code that
uses the zhmcclient package.
As an alternative to bulk-loading resources via the input dictionary, it is
also possible to add resources one by one using the add()
methods of the
faked resource manager classes, as shown in the following example:
class MyTests(unittest.TestCase):
def setUp(self):
self.session = zhmcclient_mock.FakedSession(
'fake-host', 'fake-hmc', '2.13.1', '1.8')
cpc1 = self.session.hmc.cpcs.add({
'name': 'cpc_1',
'description': 'CPC #1',
})
adapter1 = cpc1.adapters.add({
'name': 'osa_1',
'description': 'OSA #1',
'adapter-family': 'osa',
})
port1 = adapter1.ports.add({
'name': 'osa_1_1',
'description': 'OSA #1 Port #1',
})
self.client = zhmcclient.Client(self.session)
As you can see, the resources need to be added from top to bottom in the
resource tree, starting at the hmc
attribute of the faked session object.
Section Faked HMC describes all faked resource and manager classes that you can use to add resources that way.
Section Faked session describes the faked session class.
Faked session
A faked Session class for the zhmcclient package.
- class zhmcclient_mock.FakedSession(host, hmc_name, hmc_version, api_version)[source]
A faked Session class for the zhmcclient package, that can be used as a replacement for the
zhmcclient.Session
class.This class is derived from
zhmcclient.Session
.This class can be used by projects using the zhmcclient package for their unit testing. It can also be used by unit tests of the zhmcclient package itself.
This class provides a faked HMC with all of its resources that are relevant for the zhmcclient.
The faked HMC provided by this class maintains its resource state in memory as Python objects, and no communication happens to any real HMC. The faked HMC implements all HMC operations that are relevant for the zhmcclient package in a successful manner.
It is possible to populate the faked HMC with an initial resource state (see
add_resources()
).- Parameters
host (string) – HMC host.
hmc_name (string) – HMC name. Used for result of Query Version Info operation.
hmc_version (string) – HMC version string (e.g. ‘2.13.1’). Used for result of Query Version Info operation.
api_version (string) – HMC API version string (e.g. ‘1.8’). Used for result of Query Version Info operation.
- property hmc
The faked HMC provided by this faked session.
The faked HMC supports being populated with initial resource state, for example using its
zhmcclient_mock.FakedHmc.add_resources()
method.As an alternative to providing an entire resource tree, the resources can also be added one by one, from top to bottom, using the
zhmcclient_mock.FakedBaseManager.add()
methods of the respective managers (the top-level manager for CPCs can be accessed viahmc.cpcs
).- Type
- get(uri, logon_required=True)[source]
Perform the HTTP GET method against the resource identified by a URI, on the faked HMC.
- Parameters
uri (string) – Relative URI path of the resource, e.g. “/api/session”. This URI is relative to the base URL of the session (see the
base_url
property). Must not be None.logon_required (bool) –
Boolean indicating whether the operation requires that the session is logged on to the HMC.
Because this is a faked HMC, this does not perform a real logon, but it is still used to update the state in the faked HMC.
- Returns
json object with the operation result.
- Raises
- post(uri, body=None, logon_required=True, wait_for_completion=True, operation_timeout=None)[source]
Perform the HTTP POST method against the resource identified by a URI, using a provided request body, on the faked HMC.
HMC operations using HTTP POST are either synchronous or asynchronous. Asynchronous operations return the URI of an asynchronously executing job that can be queried for status and result.
Examples for synchronous operations:
With no response body: “Logon”, “Update CPC Properties”
With a response body: “Create Partition”
Examples for asynchronous operations:
With no
job-results
field in the completed job status response: “Start Partition”With a
job-results
field in the completed job status response (under certain conditions): “Activate a Blade”, or “Set CPC Power Save”
The wait_for_completion parameter of this method can be used to deal with asynchronous HMC operations in a synchronous way.
- Parameters
uri (string) – Relative URI path of the resource, e.g. “/api/session”. This URI is relative to the base URL of the session (see the
base_url
property). Must not be None.body (json object) – JSON object to be used as the HTTP request body (payload). None means the same as an empty dictionary, namely that no HTTP body is included in the request.
logon_required (bool) –
Boolean indicating whether the operation requires that the session is logged on to the HMC. For example, the “Logon” operation does not require that.
Because this is a faked HMC, this does not perform a real logon, but it is still used to update the state in the faked HMC.
wait_for_completion (bool) –
Boolean controlling whether this method should wait for completion of the requested HMC operation, as follows:
If True, this method will wait for completion of the requested operation, regardless of whether the operation is synchronous or asynchronous.
This will cause an additional entry in the time statistics to be created for the asynchronous operation and waiting for its completion. This entry will have a URI that is the targeted URI, appended with “+completion”.
If False, this method will immediately return the result of the HTTP POST method, regardless of whether the operation is synchronous or asynchronous.
operation_timeout (number) –
Timeout in seconds, when waiting for completion of an asynchronous operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used.
For wait_for_completion=True, a
OperationTimeout
is raised when the timeout expires.For wait_for_completion=False, this parameter has no effect.
- Returns
If wait_for_completion is True, returns a JSON object representing the response body of the synchronous operation, or the response body of the completed job that performed the asynchronous operation. If a synchronous operation has no response body, None is returned.
If wait_for_completion is False, returns a JSON object representing the response body of the synchronous or asynchronous operation. In case of an asynchronous operation, the JSON object will have a member named
job-uri
, whose value can be used with thequery_job_status()
method to determine the status of the job and the result of the original operation, once the job has completed.See the section in the HMC API book about the specific HMC operation and about the ‘Query Job Status’ operation, for a description of the members of the returned JSON objects.
- Return type
- Raises
- delete(uri, logon_required=True)[source]
Perform the HTTP DELETE method against the resource identified by a URI, on the faked HMC.
- Parameters
uri (string) – Relative URI path of the resource, e.g. “/api/session/{session-id}”. This URI is relative to the base URL of the session (see the
base_url
property). Must not be None.logon_required (bool) –
Boolean indicating whether the operation requires that the session is logged on to the HMC. For example, for the logoff operation, it does not make sense to first log on.
Because this is a faked HMC, this does not perform a real logon, but it is still used to update the state in the faked HMC.
- Raises
Faked HMC
The zhmcclient_mock package provides a faked HMC with all resources that are relevant for the zhmcclient package. The faked HMC is implemented as a local Python object and maintains its resource state across operations.
- class zhmcclient_mock.InputError(message)[source]
An error that is raised by the faked resource classes and indicates that the input is invalid in some way.
args[0]
will be set to a message detailing the issue.
- class zhmcclient_mock.FakedHmc(hmc_name, hmc_version, api_version)[source]
A faked HMC.
Derived from
zhmcclient_mock.FakedBaseResource
, see there for common methods and attributes.An object of this class represents a faked HMC that can have all faked resources that are relevant for the zhmcclient package.
The Python API to this class and its child resource classes is not compatible with the zhmcclient API. Instead, these classes serve as an in-memory backend for a faked session class (see
zhmcclient_mock.FakedSession
) that replaces the normalzhmcclient.Session
class.Objects of this class should not be created by the user. Instead, access the
zhmcclient_mock.FakedSession.hmc
attribute.- property enabled
Return whether the faked HMC is enabled.
- disable()[source]
Disable the faked HMC. This will cause an error to be raised when a faked session attempts to communicate with the disabled HMC.
- class zhmcclient_mock.FakedActivationProfileManager(hmc, cpc, profile_type)[source]
A manager for faked Activation Profile resources within a faked HMC (see
zhmcclient_mock.FakedHmc
).Derived from
zhmcclient_mock.FakedBaseManager
, see there for common methods and attributes.- add(properties)[source]
Add a faked Activation Profile resource.
- Parameters
properties (dict) –
Resource properties.
Special handling and requirements for certain properties:
’name’ (the OID property for this resource type!) will be auto-generated with a unique value across all instances of this resource type, if not specified.
’element-uri’ will be auto-generated based upon the OID (‘name’) property, if not specified.
’class’ will be auto-generated to ‘{profile_type}’-activation-profile’, if not specified.
- Returns
- The faked
Activation Profile resource.
- Return type
- property profile_type
Type of the activation profile (‘reset’, ‘image’, ‘load’).
- class zhmcclient_mock.FakedActivationProfile(manager, properties)[source]
A faked Activation Profile resource within a faked HMC (see
zhmcclient_mock.FakedHmc
).Derived from
zhmcclient_mock.FakedBaseResource
, see there for common methods and attributes.
- class zhmcclient_mock.FakedAdapterManager(hmc, cpc)[source]
A manager for faked Adapter resources within a faked HMC (see
zhmcclient_mock.FakedHmc
).Derived from
zhmcclient_mock.FakedBaseManager
, see there for common methods and attributes.- add(properties)[source]
Add a faked Adapter resource.
- Parameters
properties (dict) –
Resource properties.
Special handling and requirements for certain properties:
’object-id’ will be auto-generated with a unique value across all instances of this resource type, if not specified.
’object-uri’ will be auto-generated based upon the object ID, if not specified.
’class’ will be auto-generated to ‘adapter’, if not specified.
’status’ is auto-set to ‘active’, if not specified.
’adapter-family’ or ‘type’ is required to be specified, in order to determine whether the adapter is a network or storage adapter.
’adapter-family’ is auto-set based upon ‘type’, if not specified.
For network adapters, ‘network-port-uris’ is auto-set to an empty list, if not specified.
For storage adapters, ‘storage-port-uris’ is auto-set to an empty list, if not specified.
- Returns
The faked Adapter resource.
- Return type
- Raises
zhmcclient_mock.InputError – Some issue with the input properties.
- class zhmcclient_mock.FakedAdapter(manager, properties)[source]
A faked Adapter resource within a faked HMC (see
zhmcclient_mock.FakedHmc
).Derived from
zhmcclient_mock.FakedBaseResource
, see there for common methods and attributes.- __repr__()[source]
Return a string with the state of this faked Adapter resource, for debug purposes.
- property ports
The Port resources of this Adapter.
If the kind of adapter does not have ports, this is None.
- Type
- property adapter_kind
The kind of adapter, determined from the ‘adapter-family’ or ‘type’ properties. This is currently used to distinguish storage and network adapters.
Possible values are: * ‘network’ - A network adapter (OSA, ROCE, Hipersockets) * ‘storage’ - A storage adapter (FICON, FCP) * ‘other’ - Another adapter (zEDC, Crypto)
- Type
string
- class zhmcclient_mock.FakedConsoleManager(hmc, client)[source]
A manager for faked Console resources within a faked HMC (see
zhmcclient_mock.FakedHmc
).Derived from
zhmcclient_mock.FakedBaseManager
, see there for common methods and attributes.- property console
The faked Console representing the faked HMC (an object of
FakedConsole
). The object is cached.
- add(properties)[source]
Add a faked Console resource.
- Parameters
properties (dict) –
Resource properties.
Special handling and requirements for certain properties:
’object-uri’ will be auto-generated to ‘/api/console’, if not specified.
’class’ will be auto-generated to ‘console’, if not specified.
- Returns
The faked Console resource.
- Return type
- class zhmcclient_mock.FakedConsole(manager, properties)[source]
A faked Console resource within a faked HMC (see
zhmcclient_mock.FakedHmc
).Derived from
zhmcclient_mock.FakedBaseResource
, see there for common methods and attributes.- __repr__()[source]
Return a string with the state of this faked Console resource, for debug purposes.
- property storage_groups
Access to the faked Storage Group resources of this Console.
- Type
FakedStorageGroupManager
- property users
Access to the faked User resources of this Console.
- Type
- property user_roles
Access to the faked User Role resources of this Console.
- Type
- property user_patterns
Access to the faked User Pattern resources of this Console.
- property password_rules
Access to the faked Password Rule resources of this Console.
- Type
FakedPasswordRulesManager
- property tasks
Access to the faked Task resources of this Console.
- Type
- property ldap_server_definitions
Access to the faked LDAP Server Definition resources of this Console.
- property unmanaged_cpcs
Access to the faked unmanaged CPC resources of this Console.
- class zhmcclient_mock.FakedCpcManager(hmc, client)[source]
A manager for faked managed CPC resources within a faked HMC (see
zhmcclient_mock.FakedHmc
).Derived from
zhmcclient_mock.FakedBaseManager
, see there for common methods and attributes.- add(properties)[source]
Add a faked CPC resource.
- Parameters
properties (dict) –
Resource properties.
Special handling and requirements for certain properties:
’object-id’ will be auto-generated with a unique value across all instances of this resource type, if not specified.
’object-uri’ will be auto-generated based upon the object ID, if not specified.
’class’ will be auto-generated to ‘cpc’, if not specified.
’dpm-enabled’ is auto-set to False, if not specified.
’is-ensemble-member’ is auto-set to False, if not specified.
’status’ is auto-set, if not specified, as follows: If the ‘dpm-enabled’ property is True, it is set to ‘active’; otherwise it is set to ‘operating’.
- Returns
The faked CPC resource.
- Return type
- class zhmcclient_mock.FakedCpc(manager, properties)[source]
A faked managed CPC resource within a faked HMC (see
zhmcclient_mock.FakedHmc
).Derived from
zhmcclient_mock.FakedBaseResource
, see there for common methods and attributes.- property dpm_enabled
Indicates whether this CPC is in DPM mode.
This returns the value of the ‘dpm-enabled’ property.
- Type
- property lpars
Access to the faked LPAR resources of this CPC.
- Type
- property partitions
Access to the faked Partition resources of this CPC.
- property adapters
Access to the faked Adapter resources of this CPC.
- Type
- property virtual_switches
Access to the faked Virtual Switch resources of this CPC.
- property capacity_groups
Access to the faked Capacity Group resources of this CPC.
- Type
FakedCapacityGroupManager
- property reset_activation_profiles
Access to the faked Reset Activation Profile resources of this CPC.
- property image_activation_profiles
Access to the faked Image Activation Profile resources of this CPC.
- property load_activation_profiles
Access to the faked Load Activation Profile resources of this CPC.
- class zhmcclient_mock.FakedHbaManager(hmc, partition)[source]
A manager for faked HBA resources within a faked HMC (see
zhmcclient_mock.FakedHmc
).Derived from
zhmcclient_mock.FakedBaseManager
, see there for common methods and attributes.- add(properties)[source]
Add a faked HBA resource.
- Parameters
properties (dict) –
Resource properties.
Special handling and requirements for certain properties:
’element-id’ will be auto-generated with a unique value across all instances of this resource type, if not specified.
’element-uri’ will be auto-generated based upon the element ID, if not specified.
’class’ will be auto-generated to ‘hba’, if not specified.
’adapter-port-uri’ identifies the backing FCP port for this HBA and is required to be specified.
’device-number’ will be auto-generated with a unique value within the partition in the range 0x8000 to 0xFFFF, if not specified.
This method also updates the ‘hba-uris’ property in the parent faked Partition resource, by adding the URI for the faked HBA resource.
- Returns
The faked HBA resource.
- Return type
- Raises
zhmcclient_mock.InputError – Some issue with the input properties.
- class zhmcclient_mock.FakedHba(manager, properties)[source]
A faked HBA resource within a faked HMC (see
zhmcclient_mock.FakedHmc
).Derived from
zhmcclient_mock.FakedBaseResource
, see there for common methods and attributes.
- class zhmcclient_mock.FakedLdapServerDefinitionManager(hmc, console)[source]
A manager for faked LDAP Server Definition resources within a faked HMC (see
zhmcclient_mock.FakedHmc
).Derived from
zhmcclient_mock.FakedBaseManager
, see there for common methods and attributes.- add(properties)[source]
Add a faked LDAP Server Definition resource.
- Parameters
properties (dict) –
Resource properties.
Special handling and requirements for certain properties:
’element-id’ will be auto-generated with a unique value across all instances of this resource type, if not specified.
’element-uri’ will be auto-generated based upon the element ID, if not specified.
’class’ will be auto-generated to ‘ldap-server-definition’, if not specified.
- Returns
The faked LdapServerDefinition resource.
- Return type
- class zhmcclient_mock.FakedLdapServerDefinition(manager, properties)[source]
A faked LDAP Server Definition resource within a faked HMC (see
zhmcclient_mock.FakedHmc
).Derived from
zhmcclient_mock.FakedBaseResource
, see there for common methods and attributes.
- class zhmcclient_mock.FakedLparManager(hmc, cpc)[source]
A manager for faked LPAR resources within a faked HMC (see
zhmcclient_mock.FakedHmc
).Derived from
zhmcclient_mock.FakedBaseManager
, see there for common methods and attributes.- add(properties)[source]
Add a faked LPAR resource.
- Parameters
properties (dict) –
Resource properties.
Special handling and requirements for certain properties:
’object-id’ will be auto-generated with a unique value across all instances of this resource type, if not specified.
’object-uri’ will be auto-generated based upon the object ID, if not specified.
’class’ will be auto-generated to ‘logical-partition’, if not specified.
’status’ is auto-set to ‘not-activated’, if not specified.
- Returns
The faked LPAR resource.
- Return type
- class zhmcclient_mock.FakedLpar(manager, properties)[source]
A faked LPAR resource within a faked HMC (see
zhmcclient_mock.FakedHmc
).Derived from
zhmcclient_mock.FakedBaseResource
, see there for common methods and attributes.
- class zhmcclient_mock.FakedNicManager(hmc, partition)[source]
A manager for faked NIC resources within a faked HMC (see
zhmcclient_mock.FakedHmc
).Derived from
zhmcclient_mock.FakedBaseManager
, see there for common methods and attributes.- add(properties)[source]
Add a faked NIC resource.
- Parameters
properties (dict) –
Resource properties.
Special handling and requirements for certain properties:
’element-id’ will be auto-generated with a unique value across all instances of this resource type, if not specified.
’element-uri’ will be auto-generated based upon the element ID, if not specified.
’class’ will be auto-generated to ‘nic’, if not specified.
Either ‘network-adapter-port-uri’ (for backing ROCE adapters) or ‘virtual-switch-uri’(for backing OSA or Hipersockets adapters) is required to be specified.
’device-number’ will be auto-generated with a unique value within the partition in the range 0x8000 to 0xFFFF, if not specified.
This method also updates the ‘nic-uris’ property in the parent faked Partition resource, by adding the URI for the faked NIC resource.
This method also updates the ‘connected-vnic-uris’ property in the virtual switch referenced by ‘virtual-switch-uri’ property, and sets it to the URI of the faked NIC resource.
- Returns
The faked NIC resource.
- Return type
- Raises
zhmcclient_mock.InputError – Some issue with the input properties.
- class zhmcclient_mock.FakedNic(manager, properties)[source]
A faked NIC resource within a faked HMC (see
zhmcclient_mock.FakedHmc
).Derived from
zhmcclient_mock.FakedBaseResource
, see there for common methods and attributes.
- class zhmcclient_mock.FakedPartitionManager(hmc, cpc)[source]
A manager for faked Partition resources within a faked HMC (see
zhmcclient_mock.FakedHmc
).Derived from
zhmcclient_mock.FakedBaseManager
, see there for common methods and attributes.- add(properties)[source]
Add a faked Partition resource.
- Parameters
properties (dict) –
Resource properties.
Special handling and requirements for certain properties:
’object-id’ will be auto-generated with a unique value across all instances of this resource type, if not specified.
’object-uri’ will be auto-generated based upon the object ID, if not specified.
’class’ will be auto-generated to ‘partition’, if not specified.
’hba-uris’ will be auto-generated as an empty array, if not specified.
’nic-uris’ will be auto-generated as an empty array, if not specified.
’virtual-function-uris’ will be auto-generated as an empty array, if not specified.
’status’ is auto-set to ‘stopped’, if not specified.
- Returns
- The faked Partition
resource.
- Return type
- class zhmcclient_mock.FakedPartition(manager, properties)[source]
A faked Partition resource within a faked HMC (see
zhmcclient_mock.FakedHmc
).Derived from
zhmcclient_mock.FakedBaseResource
, see there for common methods and attributes.Each partition uses the device number range of 0x8000 to 0xFFFF for automatically assigned device numbers of HBAs, NICs and virtual functions. Users of the mock support should not use device numbers in that range (unless all of them are user-assigned for a particular partition).
- __repr__()[source]
Return a string with the state of this faked Partition resource, for debug purposes.
- property nics
Access to the faked NIC resources of this Partition.
- Type
- property hbas
Access to the faked HBA resources of this Partition.
- Type
- property virtual_functions
Access to the faked Virtual Function resources of this Partition.
- devno_alloc()[source]
Allocates a device number unique to this partition, in the range of 0x8000 to 0xFFFF.
- Returns
The device number as four hexadecimal digits in upper case.
- Return type
string
- Raises
ValueError – No more device numbers available in that range.
- devno_free(devno)[source]
Free a device number allocated with
devno_alloc()
.The device number must be allocated.
- Parameters
devno (string) – The device number as four hexadecimal digits.
- Raises
ValueError – Device number not in pool range or not currently allocated.
- devno_free_if_allocated(devno)[source]
Free a device number allocated with
devno_alloc()
.If the device number is not currently allocated or not in the pool range, nothing happens.
- Parameters
devno (string) – The device number as four hexadecimal digits.
- wwpn_alloc()[source]
Allocates a WWPN unique to this partition, in the range of 0xAFFEAFFE00008000 to 0xAFFEAFFE0000FFFF.
- Returns
The WWPN as 16 hexadecimal digits in upper case.
- Return type
string
- Raises
ValueError – No more WWPNs available in that range.
- wwpn_free(wwpn)[source]
Free a WWPN allocated with
wwpn_alloc()
.The WWPN must be allocated.
- Parameters
WWPN (string) – The WWPN as 16 hexadecimal digits.
- Raises
ValueError – WWPN not in pool range or not currently allocated.
- wwpn_free_if_allocated(wwpn)[source]
Free a WWPN allocated with
wwpn_alloc()
.If the WWPN is not currently allocated or not in the pool range, nothing happens.
- Parameters
WWPN (string) – The WWPN as 16 hexadecimal digits.
- class zhmcclient_mock.FakedPasswordRuleManager(hmc, console)[source]
A manager for faked Password Rule resources within a faked HMC (see
zhmcclient_mock.FakedHmc
).Derived from
zhmcclient_mock.FakedBaseManager
, see there for common methods and attributes.- add(properties)[source]
Add a faked Password Rule resource.
- Parameters
properties (dict) –
Resource properties.
Special handling and requirements for certain properties:
’element-id’ will be auto-generated with a unique value across all instances of this resource type, if not specified.
’element-uri’ will be auto-generated based upon the element ID, if not specified.
’class’ will be auto-generated to ‘password-rule’, if not specified.
- Returns
The faked Password Rule resource.
- Return type
- class zhmcclient_mock.FakedPasswordRule(manager, properties)[source]
A faked Password Rule resource within a faked HMC (see
zhmcclient_mock.FakedHmc
).Derived from
zhmcclient_mock.FakedBaseResource
, see there for common methods and attributes.
- class zhmcclient_mock.FakedPortManager(hmc, adapter)[source]
A manager for faked Adapter Port resources within a faked HMC (see
zhmcclient_mock.FakedHmc
).Derived from
zhmcclient_mock.FakedBaseManager
, see there for common methods and attributes.- add(properties)[source]
Add a faked Port resource.
- Parameters
properties (dict) –
Resource properties.
Special handling and requirements for certain properties:
’element-id’ will be auto-generated with a unique value across all instances of this resource type, if not specified.
’element-uri’ will be auto-generated based upon the element ID, if not specified.
’class’ will be auto-generated to ‘network-port’ or ‘storage-port’, if not specified.
This method also updates the ‘network-port-uris’ or ‘storage-port-uris’ property in the parent Adapter resource, by adding the URI for the faked Port resource.
- Returns
The faked Port resource.
- Return type
- class zhmcclient_mock.FakedPort(manager, properties)[source]
A faked Adapter Port resource within a faked HMC (see
zhmcclient_mock.FakedHmc
).Derived from
zhmcclient_mock.FakedBaseResource
, see there for common methods and attributes.
- class zhmcclient_mock.FakedTaskManager(hmc, console)[source]
A manager for faked Task resources within a faked HMC (see
zhmcclient_mock.FakedHmc
).Derived from
zhmcclient_mock.FakedBaseManager
, see there for common methods and attributes.- add(properties)[source]
Add a faked Task resource.
- Parameters
properties (dict) –
Resource properties.
Special handling and requirements for certain properties:
’element-id’ will be auto-generated with a unique value across all instances of this resource type, if not specified.
’element-uri’ will be auto-generated based upon the element ID, if not specified.
’class’ will be auto-generated to ‘task’, if not specified.
- Returns
The faked Task resource.
- Return type
- class zhmcclient_mock.FakedTask(manager, properties)[source]
A faked Task resource within a faked HMC (see
zhmcclient_mock.FakedHmc
).Derived from
zhmcclient_mock.FakedBaseResource
, see there for common methods and attributes.
- class zhmcclient_mock.FakedUnmanagedCpcManager(hmc, console)[source]
A manager for faked unmanaged CPC resources within a faked HMC (see
zhmcclient_mock.FakedHmc
).Derived from
zhmcclient_mock.FakedBaseManager
, see there for common methods and attributes.- add(properties)[source]
Add a faked unmanaged CPC resource.
- Parameters
properties (dict) –
Resource properties.
Special handling and requirements for certain properties:
’object-id’ will be auto-generated with a unique value across all instances of this resource type, if not specified.
’object-uri’ will be auto-generated based upon the object ID, if not specified.
- Returns
The faked unmanaged CPC resource.
- Return type
- class zhmcclient_mock.FakedUnmanagedCpc(manager, properties)[source]
A faked unmanaged CPC resource within a faked HMC (see
zhmcclient_mock.FakedHmc
).Derived from
zhmcclient_mock.FakedBaseResource
, see there for common methods and attributes.
- class zhmcclient_mock.FakedUserManager(hmc, console)[source]
A manager for faked User resources within a faked HMC (see
zhmcclient_mock.FakedHmc
).Derived from
zhmcclient_mock.FakedBaseManager
, see there for common methods and attributes.- add(properties)[source]
Add a faked User resource.
- Parameters
properties (dict) –
Resource properties.
Special handling and requirements for certain properties:
’object-id’ will be auto-generated with a unique value across all instances of this resource type, if not specified.
’object-uri’ will be auto-generated based upon the object ID, if not specified.
’class’ will be auto-generated to ‘user’, if not specified.
- Returns
The faked User resource.
- Return type
- class zhmcclient_mock.FakedUser(manager, properties)[source]
A faked User resource within a faked HMC (see
zhmcclient_mock.FakedHmc
).Derived from
zhmcclient_mock.FakedBaseResource
, see there for common methods and attributes.
- class zhmcclient_mock.FakedUserPatternManager(hmc, console)[source]
A manager for faked User Pattern resources within a faked HMC (see
zhmcclient_mock.FakedHmc
).Derived from
zhmcclient_mock.FakedBaseManager
, see there for common methods and attributes.- add(properties)[source]
Add a faked User Pattern resource.
- Parameters
properties (dict) –
Resource properties.
Special handling and requirements for certain properties:
’element-id’ will be auto-generated with a unique value across all instances of this resource type, if not specified.
’element-uri’ will be auto-generated based upon the element ID, if not specified.
’class’ will be auto-generated to ‘user-pattern’, if not specified.
- Returns
The faked User Pattern resource.
- Return type
- class zhmcclient_mock.FakedUserPattern(manager, properties)[source]
A faked User Pattern resource within a faked HMC (see
zhmcclient_mock.FakedHmc
).Derived from
zhmcclient_mock.FakedBaseResource
, see there for common methods and attributes.
- class zhmcclient_mock.FakedUserRoleManager(hmc, console)[source]
A manager for faked User Role resources within a faked HMC (see
zhmcclient_mock.FakedHmc
).Derived from
zhmcclient_mock.FakedBaseManager
, see there for common methods and attributes.- add(properties)[source]
Add a faked User Role resource.
- Parameters
properties (dict) –
Resource properties.
Special handling and requirements for certain properties:
’object-id’ will be auto-generated with a unique value across all instances of this resource type, if not specified.
’object-uri’ will be auto-generated based upon the object ID, if not specified.
’class’ will be auto-generated to ‘user-role’, if not specified.
- Returns
The faked User Role resource.
- Return type
- class zhmcclient_mock.FakedUserRole(manager, properties)[source]
A faked User Role resource within a faked HMC (see
zhmcclient_mock.FakedHmc
).Derived from
zhmcclient_mock.FakedBaseResource
, see there for common methods and attributes.
- class zhmcclient_mock.FakedVirtualFunctionManager(hmc, partition)[source]
A manager for faked Virtual Function resources within a faked HMC (see
zhmcclient_mock.FakedHmc
).Derived from
zhmcclient_mock.FakedBaseManager
, see there for common methods and attributes.- add(properties)[source]
Add a faked Virtual Function resource.
- Parameters
properties (dict) –
Resource properties.
Special handling and requirements for certain properties:
’element-id’ will be auto-generated with a unique value across all instances of this resource type, if not specified.
’element-uri’ will be auto-generated based upon the element ID, if not specified.
’class’ will be auto-generated to ‘virtual-function’, if not specified.
’device-number’ will be auto-generated with a unique value within the partition in the range 0x8000 to 0xFFFF, if not specified.
This method also updates the ‘virtual-function-uris’ property in the parent Partition resource, by adding the URI for the faked Virtual Function resource.
- Returns
- The faked Virtual
Function resource.
- Return type
- class zhmcclient_mock.FakedVirtualFunction(manager, properties)[source]
A faked Virtual Function resource within a faked HMC (see
zhmcclient_mock.FakedHmc
).Derived from
zhmcclient_mock.FakedBaseResource
, see there for common methods and attributes.
- class zhmcclient_mock.FakedVirtualSwitchManager(hmc, cpc)[source]
A manager for faked Virtual Switch resources within a faked HMC (see
zhmcclient_mock.FakedHmc
).Derived from
zhmcclient_mock.FakedBaseManager
, see there for common methods and attributes.- add(properties)[source]
Add a faked Virtual Switch resource.
- Parameters
properties (dict) –
Resource properties.
Special handling and requirements for certain properties:
’object-id’ will be auto-generated with a unique value across all instances of this resource type, if not specified.
’object-uri’ will be auto-generated based upon the object ID, if not specified.
’class’ will be auto-generated to ‘virtual-switch’, if not specified.
’connected-vnic-uris’ will be auto-generated as an empty array, if not specified.
- Returns
- The faked Virtual
Switch resource.
- Return type
- class zhmcclient_mock.FakedVirtualSwitch(manager, properties)[source]
A faked Virtual Switch resource within a faked HMC (see
zhmcclient_mock.FakedHmc
).Derived from
zhmcclient_mock.FakedBaseResource
, see there for common methods and attributes.
- class zhmcclient_mock.FakedMetricsContextManager(hmc, client)[source]
A manager for faked Metrics Context resources within a faked HMC (see
zhmcclient_mock.FakedHmc
).Derived from
zhmcclient_mock.FakedBaseManager
, see there for common methods and attributes.Example:
The following code sets up the faked data for metrics retrieval for partition usage metrics, and then retrieves the metrics:
session = FakedSession('fake-host', 'fake-hmc', '2.13.1', '1.8') client = Client(session) # URIs of (faked or real) Partitions the metric apply to: part1_uri = ... part2_uri = ... # Add a faked metric group definition for group 'partition-usage': session.hmc.metric_contexts.add_metric_group_definition( FakedMetricGroupDefinition( name='partition-usage', types=[ ('processor-usage', 'integer-metric'), ('network-usage', 'integer-metric'), ('storage-usage', 'integer-metric'), ('accelerator-usage', 'integer-metric'), ('crypto-usage', 'integer-metric'), ])) # Prepare the faked metric response for that metric group, with # data for two partitions: session.hmc.metric_contexts.add_metric_values( FakedMetricObjectValues( group_name='partition-usage', resource_uri=part1_uri, timestamp=datetime.now(), values=[ ('processor-usage', 15), ('network-usage', 0), ('storage-usage', 1), ('accelerator-usage', 0), ('crypto-usage', 0), ])) session.hmc.metric_contexts.add_metric_values( FakedMetricObjectValues( group_name='partition-usage', resource_uri=part2_uri, timestamp=datetime.now(), values=[ ('processor-usage', 17), ('network-usage', 5), ('storage-usage', 2), ('accelerator-usage', 0), ('crypto-usage', 0), ])) # Create a Metrics Context resource for one metric group: mc = client.metrics_contexts.create({ 'anticipated-frequency-seconds': 15, 'metric-groups' ['partition-usage'], }) # Retrieve the metrics for that metric context: metrics_response = mc.get_metrics()
- add(properties)[source]
Add a faked Metrics Context resource.
- Parameters
properties (dict) –
Resource properties, as defined in the description of the
FakedMetricsContext
class.Special handling and requirements for certain properties:
’fake-id’ will be auto-generated with a unique value across all instances of this resource type, if not specified.
’fake-uri’ will be auto-generated based upon the ‘fake-id’ property, if not specified.
- Returns
The faked Metrics Context resource.
- Return type
- add_metric_group_definition(definition)[source]
Add a faked metric group definition.
The definition will be used:
For later addition of faked metrics responses.
For returning the metric-group-info objects in the response of the Create Metrics Context operations.
For defined metric groups, see chapter “Metric groups” in the HMC API book.
- Parameters
( (definition) – class:~zhmcclient.FakedMetricGroupDefinition`): Definition of the metric group.
- Raises
ValueError – A metric group definition with this name already exists.
- get_metric_group_definition(group_name)[source]
Get a faked metric group definition by its group name.
- Parameters
group_name (string) – Name of the metric group.
- Returns
- class:~zhmcclient.FakedMetricGroupDefinition`: Definition of the
metric group.
- Raises
ValueError – A metric group definition with this name does not exist.
- get_metric_group_definition_names()[source]
Get the group names of all faked metric group definitions.
- Returns
- The group names, in the order their metric
group definitions had been added.
- Return type
iterable of string
- add_metric_values(values)[source]
Add one set of faked metric values for a particular resource to the metrics response for a particular metric group, for later retrieval.
For defined metric groups, see chapter “Metric groups” in the HMC API book.
- Parameters
values (
FakedMetricObjectValues
) – The set of metric values to be added. It specifies the resource URI and the targeted metric group name.
- get_metric_values(group_name)[source]
Get the faked metric values for a metric group, by its metric group name.
The result includes all metric object values added earlier for that metric group name, using
add_metric_object_values()
i.e. the metric values for all resources and all points in time that were added.- Parameters
group_name (string) – Name of the metric group.
- Returns
- The metric
values for that metric group, in the order they had been added.
- Return type
iterable of
FakedMetricObjectValues
- Raises
ValueError – Metric values for this group name do not exist.
- class zhmcclient_mock.FakedMetricsContext(manager, properties)[source]
A faked Metrics Context resource within a faked HMC (see
zhmcclient_mock.FakedHmc
).Derived from
zhmcclient_mock.FakedBaseResource
, see there for common methods and attributes.The Metrics Context “resource” is really a service and therefore does not have a data model defined in the HMC API book. In order to fit into the zhmcclient mock framework, the faked Metrics Context in the zhmcclient mock framework is treated like all other faked resources and does have a data model.
Data Model:
‘fake-id’ (string): Object ID of the resource.
Initialization: Optional. If omitted, it will be auto-generated.
- ‘fake-uri’ (string): Resource URI of the resource (used for Get
Metrics operation).
Initialization: Optional. If omitted, it will be auto-generated from the Object ID.
- ‘anticipated-frequency-seconds’ (integer):
The number of seconds the client anticipates will elapse between metrics retrievals using this context. The minimum accepted value is 15.
Initialization: Required.
- ‘metric-groups’ (list of string):
The metric group names to be returned by a metric retrieval using this context.
Initialization: Optional. If omitted or the empty list, all metric groups that are valid for the operational mode of each CPC will be returned.
- get_metric_group_definitions()[source]
Get the faked metric group definitions for this context object that are to be returned from its create operation.
If a ‘metric-groups’ property had been specified for this context, only those faked metric group definitions of its manager object that are in that list, are included in the result. Otherwise, all metric group definitions of its manager are included in the result.
- Returns
- class:~zhmcclient.FakedMetricGroupDefinition`: The faked
metric group definitions, in the order they had been added.
- Return type
iterable of
- get_metric_group_infos()[source]
Get the faked metric group definitions for this context object that are to be returned from its create operation, in the format needed for the “Create Metrics Context” operation response.
- Returns
- “metric-group-infos” JSON object as described for the “Create Metrics
Context “operation response.
- get_metric_values()[source]
Get the faked metrics, for all metric groups and all resources that have been prepared on the manager object of this context object.
- Returns
- The faked
metrics, in the order they had been added, where:
group_name (string): Metric group name.
- values (:class:~zhmcclient.FakedMetricObjectValues`):
The metric values for one resource at one point in time.
- Return type
iterable of tuple (group_name, iterable of values)
- get_metric_values_response()[source]
Get the faked metrics, for all metric groups and all resources that have been prepared on the manager object of this context object, as a string in the format needed for the “Get Metrics” operation response.
- Returns
- “MetricsResponse” string as described for the “Get Metrics”
operation response.
- class zhmcclient_mock.FakedBaseManager(hmc, parent, resource_class, base_uri, oid_prop, uri_prop, class_value)[source]
A base class for manager classes for faked resources in the faked HMC.
- property parent
The parent (scoping resource) for this manager (an object of a derived class of
FakedBaseResource
).
- property resource_class
The resource class managed by this manager (a derived class of
FakedBaseResource
).
- property base_uri
The base URI for URIs of resources managed by this manager.
- property oid_prop
The name of the resource property for the object ID (‘object-id’ or ‘element-id’ or ‘name’).
- property uri_prop
The name of the resource property for the object URI (‘object-uri’ or ‘element-uri’).
- property class_value
The value for the “class” property of resources managed by this manager, as defined in the data model for the resource. For example, for LPAR resources this is set to ‘logical-partition’.
- add(properties)[source]
Add a faked resource to this manager.
For URI-based lookup, the resource is also added to the faked HMC.
- Parameters
properties (dict) – Resource properties. If the URI property (e.g. ‘object-uri’) or the object ID property (e.g. ‘object-id’) are not specified, they will be auto-generated.
- Returns
The faked resource object.
- Return type
- remove(oid)[source]
Remove a faked resource from this manager.
- Parameters
oid (string) – The object ID of the resource (e.g. value of the ‘object-uri’ property).
- lookup_by_oid(oid)[source]
Look up a faked resource by its object ID, in the scope of this manager.
- Parameters
oid (string) – The object ID of the faked resource (e.g. value of the ‘object-id’ property).
- Returns
The faked resource object.
- Return type
- Raises
KeyError – No resource found for this object ID.
- class zhmcclient_mock.FakedBaseResource(manager, properties)[source]
A base class for faked resource classes in the faked HMC.
- __repr__()[source]
Return a string with the state of this faked resource, for debug purposes.
Note that the derived faked resource classes that have child resources have their own __repr__() methods, because only they know which child resources they have.
- property manager
The manager for this resource (a derived class of
FakedBaseManager
).
- property properties
The properties of this resource (a dictionary).
- property oid
The object ID (property ‘object-id’ or ‘element-id’) of this resource.
- property uri
The object URI (property ‘object-uri’ or ‘element-uri’) of this resource.
- property name
The name (property ‘name’) of this resource.
- Raises
KeyError – Resource does not have a ‘name’ property.
- update(properties)[source]
update the properties of this resource.
- Parameters
properties (dict) – Resource properties to be updated. Any other properties remain unchanged.
- add_resources(resources)[source]
Add faked child resources to this resource, from the provided resource definitions.
Duplicate resource names in the same scope are not permitted.
Although this method is typically used to initially load the faked HMC with resource state just once, it can be invoked multiple times and can also be invoked on faked resources (e.g. on a faked CPC).
- Parameters
resources (dict) –
resource dictionary with definitions of faked child resources to be added. For an explanation of how the resource dictionary is set up, see the examples below.
For requirements on and auto-generation of certain resource properties, see the
add()
methods of the various faked resource managers (e.g.zhmcclient_mock.FakedCpcManager.add()
). For example, the object-id or element-id properties and the corresponding uri properties are always auto-generated.The resource dictionary specifies a tree of resource managers and resources, in an alternating manner. It starts with the resource managers of child resources of the target resource, which contains a list of those child resources. For an HMC, the CPCs managed by the HMC would be its child resources.
Each resource specifies its own properties (
properties
key) and the resource managers for its child resources. For example, the CPC resource specifies its adapter child resources using theadapters
key. The keys for the child resource managers are the attribute names of these resource managers in the parent resource. For example, theadapters
key is named after thezhmcclient.Cpc.adapters
attribute (which has the same name as in its corresponding faked CPC resource:zhmcclient_mock.FakedCpc.adapters
).- Raises
zhmcclient_mock.InputError – Some issue with the input resources.
Examples
Example for targeting a faked HMC for adding a CPC with one adapter:
resources = { 'cpcs': [ # name of manager attribute for this resource { 'properties': { 'name': 'cpc_1', }, 'adapters': [ # name of manager attribute for this # resource { 'properties': { 'object-id': '12', 'name': 'ad_1', }, 'ports': [ { 'properties': { 'name': 'port_1', } }, ], }, ], }, ], }
Example for targeting a faked CPC for adding an LPAR and a load activation profile:
resources = { 'lpars': [ # name of manager attribute for this resource { 'properties': { # object-id is not provided -> auto-generated # object-uri is not provided -> auto-generated 'name': 'lpar_1', }, }, ], 'load_activation_profiles': [ # name of manager attribute { 'properties': { # object-id is not provided -> auto-generated # object-uri is not provided -> auto-generated 'name': 'lpar_1', }, }, ], }
URI handler
A module with various handler classes for the HTTP methods against HMC URIs, based on the faked HMC.
Most handler classes do not need to be documented, but some of them have methods that can be mocked in order to provoke non-standard behavior in the handling of the HTTP methods.
- class zhmcclient_mock.LparActivateHandler[source]
A handler class for the “Activate Logical Partition” operation.
- static get_status()[source]
Status retrieval method that returns the status the faked Lpar will have after completion of the “Activate Logical Partition” operation.
This method returns the successful status ‘not-operating’ for LPARs that do not auto-load their OSs, and can be mocked by testcases to return a different status (e.g. ‘operating’ for LPARs that do auto-load, or ‘acceptable’ or ‘exceptions’).
- class zhmcclient_mock.LparDeactivateHandler[source]
A handler class for the “Deactivate Logical Partition” operation.
- static get_status()[source]
Status retrieval method that returns the status the faked Lpar will have after completion of the “Deactivate Logical Partition” operation.
This method returns the successful status ‘not-activated’, and can be mocked by testcases to return a different status (e.g. ‘exceptions’).
- class zhmcclient_mock.LparLoadHandler[source]
A handler class for the “Load Logical Partition” operation.
- static get_status()[source]
Status retrieval method that returns the status the faked Lpar will have after completion of the “Load Logical Partition” operation.
This method returns the successful status ‘operating’, and can be mocked by testcases to return a different status (e.g. ‘acceptable’ or ‘exceptions’).
Development
This section only needs to be read by developers of the zhmcclient package. People that want to make a fix or develop some extension, and people that want to test the project are also considered developers for the purpose of this section.
Code of Conduct
Help us keep zhmcclient open and inclusive. Please read and follow our Code of Conduct.
Repository
The repository for zhmcclient is on GitHub:
Setting up the development environment
The development environment is pretty easy to set up.
Besides having a supported operating system with a supported Python version (see Supported environments), it is recommended that you set up a virtual Python environment.
Then, with a virtual Python environment active, clone the Git repo of this
project and prepare the development environment with make develop
:
$ git clone git@github.com:zhmcclient/python-zhmcclient.git
$ cd python-zhmcclient
$ make develop
This will install all prerequisites the package needs to run, as well as all prerequisites that you need for development.
Generally, this project uses Make to do things in the currently active
Python environment. The command make help
(or just make
) displays a
list of valid Make targets and a short description of what each target does.
Building the documentation
The ReadTheDocs (RTD) site is used to publish the documentation for the zhmcclient package at http://python-zhmcclient.readthedocs.io/
This page automatically gets updated whenever the master
branch of the
Git repo for this package changes.
In order to build the documentation locally from the Git work directory, issue:
$ make builddoc
The top-level document to open with a web browser will be
build_doc/html/docs/index.html
.
Testing
To run unit tests in the currently active Python environment, issue one of
these example variants of make test
:
$ make test # Run all unit tests
$ TESTCASES=test_resource.py make test # Run only this test source file
$ TESTCASES=TestInit make test # Run only this test class
$ TESTCASES="TestInit or TestSet" make test # py.test -k expressions are possible
To run the unit tests and some more commands that verify the project is in good shape in all supported Python environments, use Tox:
$ tox # Run all tests on all supported Python versions
$ tox -e py27 # Run all tests on Python 2.7
$ tox -e py27 test_resource.py # Run only this test source file on Python 2.7
$ tox -e py27 TestInit # Run only this test class on Python 2.7
$ tox -e py27 TestInit or TestSet # py.test -k expressions are possible
The positional arguments of the tox
command are passed to py.test
using
its -k
option. Invoke py.test --help
for details on the expression
syntax of its -k
option.
Running function tests against a real HMC and CPC
The function tests (in tests/function/test_*.py
) can be run against a
faked HMC/CPC (using the zhmcclient mock support), or against a real HMC/CPC.
By default, the function tests are run against the faked HMC/CPC. To run them against a real HMC/CPC, you must:
Specify the name of the target CPC in the
ZHMC_TEST_CPC
environment variable. This environment variable is the control point that decides between using a real HMC/CPC and using the faked environment:export ZHMC_TEST_CPC=S67B
Have an HMC credentials file at location
examples/hmccreds.yaml
that specifies the target CPC (among possibly further CPCs) in itscpcs
item:cpcs: S67B: description: "z13s in DPM mode" contact: "Joe" hmc_host: "10.11.12.13" hmc_userid: myuserid hmc_password: mypassword # ... more CPCs
There is an example HMC credentials file in the repo, at
examples/example_hmccreds.yaml
. For a description of its format, see
Format of the HMC credentials file.
Enabling logging for function tests
The function tests always log to stderr. What can be logged are the following two components:
api
: Calls to and returns from zhmcclient API functions (at debug level).hmc
: Interactions with the HMC (i.e. HTTP requests and responses, at debug level).
By default, the log component and level is set to:
all=warning
meaning that all components log at warning level or higher.
To set different log levels for the log components, set the ZHMC_LOG
environment variable as follows:
export ZHMC_LOG=COMP=LEVEL[,COMP=LEVEL[,...]]
Where:
COMP
is one of:all
,api
,hmc
.LEVEL
is one of:error
,warning
,info
,debug
.
For example, to enable logging of the zhmcclient API calls and the interactions with the HMC, use:
export ZHMC_LOG=api=debug,hmc=debug
or, shorter:
export ZHMC_LOG=all=debug
Format of the HMC credentials file
The HMC credentials file is used for specifying real HMCs/CPCs to be used by
function tests. Its syntax is YAML, and the cpcs
item relevant for function
testing has the following structure:
cpcs:
"CPC1":
description: "z13 test system"
contact: "Amy"
hmc_host: "10.10.10.11" # required
hmc_userid: "myuser1" # required
hmc_password: "mypassword1" # required
"CPC2":
description: "z14 development system"
contact: "Bob"
hmc_host: "10.10.10.12"
hmc_userid: "myuser2"
hmc_password: "mypassword2"
In the example above, any words in double quotes are data and can change, and any words without double quotes are considered keywords and must be specified as shown.
“CPC1” and “CPC2” are CPC names that are used to select an entry in the file. The entry for a CPC contains data about the HMC managing that CPC, with its host, userid and password. If two CPCs are managed by the same HMC, there would be two CPC entries with the same HMC data.
Contributing
Third party contributions to this project are welcome!
In order to contribute, create a Git pull request, considering this:
Test is required.
Each commit should only contain one “logical” change.
A “logical” change should be put into one commit, and not split over multiple commits.
Large new features should be split into stages.
The commit message should not only summarize what you have done, but explain why the change is useful.
The commit message must follow the format explained below.
What comprises a “logical” change is subject to sound judgement. Sometimes, it makes sense to produce a set of commits for a feature (even if not large). For example, a first commit may introduce a (presumably) compatible API change without exploitation of that feature. With only this commit applied, it should be demonstrable that everything is still working as before. The next commit may be the exploitation of the feature in other components.
For further discussion of good and bad practices regarding commits, see:
Format of commit messages
A commit message must start with a short summary line, followed by a blank line.
Optionally, the summary line may start with an identifier that helps identifying the type of change or the component that is affected, followed by a colon.
It can include a more detailed description after the summary line. This is where you explain why the change was done, and summarize what was done.
It must end with the DCO (Developer Certificate of Origin) sign-off line in the format shown in the example below, using your name and a valid email address of yours. The DCO sign-off line certifies that you followed the rules stated in DCO 1.1. In short, you certify that you wrote the patch or otherwise have the right to pass it on as an open-source patch.
We use GitCop during creation of a pull request to check whether the commit messages in the pull request comply to this format. If the commit messages do not comply, GitCop will add a comment to the pull request with a description of what was wrong.
Example commit message:
cookies: Add support for delivering cookies
Cookies are important for many people. This change adds a pluggable API for
delivering cookies to the user, and provides a default implementation.
Signed-off-by: Random J Developer <random@developer.org>
Use git commit --amend
to edit the commit message, if you need to.
Use the --signoff
(-s
) option of git commit
to append a sign-off
line to the commit message with your name and email as known by Git.
If you like filling out the commit message in an editor instead of using
the -m
option of git commit
, you can automate the presence of the
sign-off line by using a commit template file:
Create a file outside of the repo (say,
~/.git-signoff.template
) that contains, for example:<one-line subject> <detailed description> Signed-off-by: Random J Developer <random@developer.org>
Configure Git to use that file as a commit template for your repo:
git config commit.template ~/.git-signoff.template
Releasing a version
This section shows the steps for releasing a version to PyPI.
It covers all variants of versions that can be released:
Releasing a new major version (Mnew.0.0) based on the master branch
Releasing a new minor version (M.Nnew.0) based on the master branch
Releasing a new update version (M.N.Unew) based on the stable branch of its minor version
This description assumes that you are authorized to push to the remote repo
at https://github.com/zhmcclient/python-zhmcclient and that the remote repo
has the remote name origin
in your local clone.
Any commands in the following steps are executed in the main directory of your local clone of the python-zhmcclient Git repo.
Set shell variables for the version that is being released and the branch it is based on:
MNU
- Full version M.N.U that is being releasedMN
- Major and minor version M.N of that full versionBRANCH
- Name of the branch the version that is being released is based on
When releasing a new major version (e.g.
1.0.0
) based on the master branch:MNU=1.0.0 MN=1.0 BRANCH=master
When releasing a new minor version (e.g.
0.9.0
) based on the master branch:MNU=0.9.0 MN=0.9 BRANCH=master
When releasing a new update version (e.g.
0.8.1
) based on the stable branch of its minor version:MNU=0.8.1 MN=0.8 BRANCH=stable_${MN}
Create a topic branch for the version that is being released:
git checkout ${BRANCH} git pull git checkout -b release_${MNU}
Edit the version file:
vi zhmcclient/_version.py
and set the
__version__
variable to the version that is being released:__version__ = 'M.N.U'
Edit the change log:
vi docs/changes.rst
and make the following changes in the section of the version that is being released:
Finalize the version.
Change the release date to today’s date.
Make sure that all changes are described.
Make sure the items shown in the change log are relevant for and understandable by users.
In the “Known issues” list item, remove the link to the issue tracker and add text for any known issues you want users to know about.
Remove all empty list items.
When releasing based on the master branch, edit the GitHub workflow file
test.yml
:vi .github/workflows/test.yml
and in the
on
section, increase the version of thestable_*
branch to the new stable branchstable_M.N
created earlier:on: schedule: . . . push: branches: [ master, stable_M.N ] pull_request: branches: [ master, stable_M.N ]
Commit your changes and push the topic branch to the remote repo:
git status # Double check the changed files git commit -asm "Release ${MNU}" git push --set-upstream origin release_${MNU}
On GitHub, create a Pull Request for branch
release_M.N.U
. This will trigger the CI runs.Important: When creating Pull Requests, GitHub by default targets the
master
branch. When releasing based on a stable branch, you need to change the target branch of the Pull Request tostable_M.N
.On GitHub, close milestone
M.N.U
.On GitHub, once the checks for the Pull Request for branch
start_M.N.U
have succeeded, merge the Pull Request (no review is needed). This automatically deletes the branch on GitHub.Add a new tag for the version that is being released and push it to the remote repo. Clean up the local repo:
git checkout ${BRANCH} git pull git tag -f ${MNU} git push -f --tags git branch -D release_${MNU} git branch -D -r origin/release_${MNU}
When releasing based on the master branch, create and push a new stable branch for the same minor version:
git checkout -b stable_${MN} git push --set-upstream origin stable_${MN} git checkout ${BRANCH}
Note that no GitHub Pull Request is created for any
stable_*
branch.On GitHub, edit the new tag
M.N.U
, and create a release description on it. This will cause it to appear in the Release tab.You can see the tags in GitHub via Code -> Releases -> Tags.
On ReadTheDocs, activate the new version
M.N.U
:Go to https://readthedocs.org/projects/python-zhmcclient/versions/ and log in.
Activate the new version
M.N.U
(it should be automatically active)This triggers a build of that version. Verify that the build succeeds and that new version is shown in the version selection popup at https://python-zhmcclient.readthedocs.io/
Upload the package to PyPI:
make upload
This will show the package version and will ask for confirmation.
Attention! This only works once for each version. You cannot release the same version twice to PyPI.
Verify that the released version arrived on PyPI at https://pypi.python.org/pypi/zhmcclient/
Starting a new version
This section shows the steps for starting development of a new version.
This section covers all variants of new versions:
Starting a new major version (Mnew.0.0) based on the master branch
Starting a new minor version (M.Nnew.0) based on the master branch
Starting a new update version (M.N.Unew) based on the stable branch of its minor version
This description assumes that you are authorized to push to the remote repo
at https://github.com/zhmcclient/python-zhmcclient and that the remote repo
has the remote name origin
in your local clone.
Any commands in the following steps are executed in the main directory of your local clone of the python-zhmcclient Git repo.
Set shell variables for the version that is being started and the branch it is based on:
MNU
- Full version M.N.U that is being startedMN
- Major and minor version M.N of that full versionBRANCH
- Name of the branch the version that is being started is based on
When starting a new major version (e.g.
1.0.0
) based on the master branch:MNU=1.0.0 MN=1.0 BRANCH=master
When starting a new minor version (e.g.
0.9.0
) based on the master branch:MNU=0.9.0 MN=0.9 BRANCH=master
When starting a new minor version (e.g.
0.8.1
) based on the stable branch of its minor version:MNU=0.8.1 MN=0.8 BRANCH=stable_${MN}
Create a topic branch for the version that is being started:
git checkout ${BRANCH} git pull git checkout -b start_${MNU}
Edit the version file:
vi zhmcclient/_version.py
and update the version to a draft version of the version that is being started:
__version__ = 'M.N.U.dev1'
Edit the change log:
vi docs/changes.rst
and insert the following section before the top-most section:
Version M.N.U.dev1 ^^^^^^^^^^^^^^^^^^ This version contains all fixes up to version M.N-1.x. Released: not yet **Incompatible changes:** **Deprecations:** **Bug fixes:** **Enhancements:** **Cleanup:** **Known issues:** * See `list of open issues`_. .. _`list of open issues`: https://github.com/zhmcclient/python-zhmcclient/issues
Commit your changes and push them to the remote repo:
git status # Double check the changed files git commit -asm "Start ${MNU}" git push --set-upstream origin start_${MNU}
On GitHub, create a Pull Request for branch
start_M.N.U
.Important: When creating Pull Requests, GitHub by default targets the
master
branch. When starting a version based on a stable branch, you need to change the target branch of the Pull Request tostable_M.N
.On GitHub, create a milestone for the new version
M.N.U
.You can create a milestone in GitHub via Issues -> Milestones -> New Milestone.
On GitHub, go through all open issues and pull requests that still have milestones for previous releases set, and either set them to the new milestone, or to have no milestone.
On GitHub, once the checks for the Pull Request for branch
start_M.N.U
have succeeded, merge the Pull Request (no review is needed). This automatically deletes the branch on GitHub.Update and clean up the local repo:
git checkout ${BRANCH} git pull git branch -D start_${MNU} git branch -D -r origin/start_${MNU}
Security
This section contains information about the security of the communication between the ‘zhmcclient’ client and the HMC.
HMC Web Services API
This section covers the communication between the ‘zhmcclient’ package and the HMC Web Services API on port 6794. The ‘zhmcclient’ package uses the Python ‘requests’ package for this purpose.
SSL/TLS protocol version
The HMC supports HTTPS at its Web Services API port, i.e. it requires the use of SSL/TLS-based sockets. The HMC can be configured to require TLS 1.2, or to tolerate the older SSLv3 protocol in addition. Since SSLv3 is considered insecure, it is highly recommended to configure the HMC to require TLS 1.2 and to disable SSLv3 and RC4. This can be configured in the HMC task “Customize Console Services”. See also the HMC Security book and Chapter 3 “Invoking API operations” in the HMC API book.
The ‘zhmcclient’ package uses the default settings of the ‘requests’ package regarding the SSL/TLS version, which causes the highest version supported by both client and HMC to be used. The highest supported SSL/TLS version used by the client is determined by the OpenSSL version used by Python on the client side. OpenSSL 1.0.1 or higher is required to support TLS 1.2. You can display the OpenSSL version used by Python using this command:
$ python -c "import ssl; print(ssl.OPENSSL_VERSION)"
OpenSSL 1.1.1i 8 Dec 2020
HMC certificate
By default, the HMC is configured with a self-signed certificate. That is the X.509 certificate presented by the HMC as the server certificate during SSL/TLS handshake at its Web Services API.
Starting with version 0.31, the zhmcclient will reject self-signed certificates by default.
The HMC should be configured to use a CA-verifiable certificate. This can be done in the HMC task “Certificate Management”. See also the HMC Security book and Chapter 3 “Invoking API operations” in the HMC API book.
Starting with version 0.31, the zhmcclient provides a control knob for the
verification of the HMC certificate via the verify_cert
init parameter of
the zhmcclient.Session
class. That init parameter can be set to:
False: Do not verify the HMC certificate. Not verifying the HMC certificate means the zhmcclient will not detect hostname mismatches, expired certificates, revoked certificates, or otherwise invalid certificates. Since this mode makes the connection vulnerable to man-in-the-middle attacks, it is insecure and should not be used in production environments.
True (default): Verify the HMC certificate using the CA certificates from the first of these locations:
The file or directory in the
REQUESTS_CA_BUNDLE
env.var, if setThe file or directory in the
CURL_CA_BUNDLE
env.var, if setThe Python ‘certifi’ package (which contains the Mozilla Included CA Certificate List).
string: Path name of a certificate file or directory. Verify the HMC certificate using the CA certificates in that file or directory.
If a certificate file is specified (using any of the ways listed above), that file must be in PEM format and must contain all CA certificates that are supposed to be used. Usually they are in the order from leaf to root, but that is not a hard requirement. The single certificates are concatenated in the file.
If a certificate directory is specified (using any of the ways listed above),
it must contain PEM files with all CA certificates that are supposed to be used,
and copies of the PEM files or symbolic links to them in the hashed format
created by the OpenSSL command c_rehash
.
An X.509 certificate in PEM format is base64-encoded, begins with the line
-----BEGIN CERTIFICATE-----
, and ends with the line
-----END CERTIFICATE-----
.
More information about the PEM format is for example on this
www.ssl.com page
or in this serverfault.com answer.
Since the zhmcclient package uses the ‘requests’ package for the communication with the Web Services API of the HMC, the behavior described above actually comes from the ‘requests’ package. Unfortunately, its documentation about certificate verification is somewhat brief, see SSL Cert Verification.
Note that setting the REQUESTS_CA_BUNDLE
or CURL_CA_BUNDLE
environment
variables influences other programs that use these variables, too.
Cipher suites
During SSL/TLS handshake, the cipher suite to be used for various aspects in the communication is negotiated between the HMC and the ‘zhmcclient’ client.
The set of cipher suites enabled for the HMC Web Services API can be configured in the HMC task “Certificate Management”. See also the HMC Security book for details.
The ‘zhmcclient’ package uses the default cipher suites of the ‘requests’ package, which are the default cipher suites used by the standard Python ‘ssl’ module. By default, the CPython implementation uses OpenSSL. Python PEP 644 targeted for Python 3.10 contains information about which versions of Python support which versions of OpenSSL.
As of Python 3.9, there is no function yet that lists the supported ciphers.
You can display the OpenSSL version used by the Python on your system with this command:
$ python -c "import ssl; print(ssl.OPENSSL_VERSION)"
OpenSSL 1.1.1i 8 Dec 2020
The TLS 1.2 compatible ciphers that are supported by OpenSSL on your system can be listed with this command:
$ openssl ciphers -tls1_2 -s -v | sort
AES128-GCM-SHA256 TLSv1.2 Kx=RSA Au=RSA Enc=AESGCM(128) Mac=AEAD
AES128-SHA SSLv3 Kx=RSA Au=RSA Enc=AES(128) Mac=SHA1
AES128-SHA256 TLSv1.2 Kx=RSA Au=RSA Enc=AES(128) Mac=SHA256
. . .
The SSL/TLS version shown in the output is the minimum SSL/TLS protocol version needed to use the cipher, not the actual version that is used.
Brief expansion of the output field names used by this command:
Kx = Key Exchange
Au = Authentication
Enc = Encryption
Mac = Message Authentication Code
HMC Web Services API notifications
The HMC Web Services API supports notifications that are sent from the HMC to a client. The HMC supports two protocols for this purpose:
STOMP (Streaming Text Oriented Messaging Protocol) on port 61612.
OpenWire on port 61617.
These protocols can be enabled on the HMC task “Customize API Settings”. See also the HMC Security book for details.
The ‘zhmcclient’ package supports the STOMP protocol for HMC notifications and uses the Python ‘stomp.py’ package for this purpose.
Appendix
This section contains information that is referenced from other sections, and that does not really need to be read in sequence.
Troubleshooting
This section describes a few issues and how to address them.
ConnectionError with SSLV3_ALERT_HANDSHAKE_FAILURE
Symptom: The ‘zhmcclient’ package raises a zhmcclient.ConnectionError
exception with the following message:
[SSL: SSLV3_ALERT_HANDSHAKE_FAILURE] sslv3 alert handshake failure (_ssl.c:1123)
The root cause is very likely that the HMC is set to TLS 1.2 only and has disabled SSLv3 compatibility, and the OpenSSL package used by the Python on your client system does not support TLS 1.2 yet.
To check which OpenSSL version is used by the Python on your client system, issue this command (sample output is shown):
$ python -c "import ssl; print(ssl.OPENSSL_VERSION)"
OpenSSL 1.1.1i 8 Dec 2020
using the Python you have used when the ‘zhmcclient’ package raised the exception.
To have support for TLS 1.2 you need OpenSSL version 1.0.1 or higher.
See also the Security section.
ConnectionError with CERTIFICATE_VERIFY_FAILED: self signed certificate
Symptom: The ‘zhmcclient’ package raises a zhmcclient.ConnectionError
exception with the following message:
[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self signed certificate (_ssl.c:1125)
The root cause is that the HMC is set up to use a self-signed certificate
and the client has used verify_cert=True
in the zhmcclient.Session
initialization, which is the default. That causes the client to use the
Python ‘certifi’ package for verification of the server certificate and the
‘certifi’ package provides the CA certificates from the
Mozilla Included CA Certificate List
which does not include the self-signed certificate.
The issue can be temporarily circumvented by specifying verify_cert=False
,
which disables the verification of the server certificate. Since that makes
the connection vulnerable to man-in-the-middle attacks, it should be done
only as a temporary circumvention.
The solution is to have your HMC administrator obtain a CA-verifiable certificate and to install that in the HMC.
See also the Security section.
Base classes for resources
Base definitions for resource manager classes.
Resource manager classes exist for each resource type and are helper classes that provide functionality common for the resource type.
Resource manager objects are not necessarily singleton objects, because they have a scope of a certain set of resource objects. For example, the resource manager object for LPARs exists once for each CPC managed by the HMC, and the resource object scope of each LPAR manager object is the set of LPARs in that CPC.
- class zhmcclient.BaseManager(resource_class, class_name, session, parent, base_uri, oid_prop, uri_prop, name_prop, query_props, list_has_name=True)[source]
Abstract base class for manager classes (e.g.
CpcManager
).It defines the interface for the derived manager classes, and implements methods that have a common implementation for the derived manager classes.
Objects of derived manager classes should not be created by users of this package by simply instantiating them. Instead, such objects are created by this package as instance variables of
Client
and other resource objects, e.g.cpcs
. For this reason, the __init__() method of this class and of its derived manager classes are considered internal interfaces and their parameters are not documented and may change incompatibly.- invalidate_cache()[source]
Invalidate the Name-URI cache of this manager.
The zhmcclient maintains a Name-URI cache in each manager object, which caches the mappings between resource URIs and resource names, to speed up certain zhmcclient methods.
The Name-URI cache is properly updated during changes on the resource name (e.g. via
update_properties()
) or changes on the resource URI (e.g. via resource creation or deletion), if these changes are performed through the same Python manager object.However, changes performed through a different manager object (e.g. because a different session, client or parent resource object was used), or changes performed in a different Python process, or changes performed via other means than the zhmcclient library (e.g. directly on the HMC) will not automatically update the Name-URI cache of this manager.
In cases where the resource name or resource URI are effected by such changes, the Name-URI cache can be manually invalidated by the user, using this method.
Note that the Name-URI cache automatically invalidates itself after a certain time since the last invalidation. That auto invalidation time can be configured using the
name_uri_cache_timetolive
attribute of theRetryTimeoutConfig
class.
- property resource_class
The Python class of the parent resource of this manager.
- property class_name
The resource class name
- property parent
Subclass of
BaseResource
: Parent resource defining the scope for this manager.None, if the manager has no parent, i.e. when it manages top-level resources.
- resource_object(uri_or_oid, props=None)[source]
Return a minimalistic Python resource object for this resource class, that is scoped to this manager.
This method is an internal helper function and is not normally called by users.
The returned resource object will have the following minimal set of properties set automatically:
object-uri
object-id
parent
class
Additional properties for the Python resource object can be specified by the caller.
- Parameters
uri_or_oid (string) – object-uri or object-id of the resource.
props (dict) – Property values in addition to the minimal list of properties that are set automatically (see above).
- Returns
A Python resource object for this resource class.
- Return type
Subclass of
BaseResource
- findall(**filter_args)[source]
Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g. for CPCs, a list of
Cpc
objects is returned).Any resource property may be specified in a filter argument. For details about filter arguments, see Filtering.
The zhmcclient implementation handles the specified properties in an optimized way: Properties that can be filtered on the HMC are actually filtered there (this varies by resource type), and the remaining properties are filtered on the client side.
If the “name” property is specified as the only filter argument, an optimized lookup is performed that uses a name-to-URI cache in this manager object. This this optimized lookup uses the specified match value for exact matching and is not interpreted as a regular expression.
Authorization requirements:
see the list() method in the derived classes.
- Parameters
**filter_args – All keyword arguments are used as filter arguments. Specifying no keyword arguments causes no filtering to happen. See the examples for usage details.
- Returns
List of resource objects in scope of this manager object that match the filter arguments. These resource objects have a minimal set of properties.
- Raises
Exceptions raised by the list() methods in derived resource manager classes (see Reference: Resources).
Examples:
The following example finds partitions in a CPC by status. Because the ‘status’ resource property is also a valid Python variable name, there are two ways for the caller to specify the filter arguments for this method:
As named parameters:
run_states = ['active', 'degraded'] run_parts = cpc.partitions.find(status=run_states)
As a parameter dictionary:
run_parts = cpc.partitions.find(**{'status': run_states})
The following example finds adapters of the OSA family in a CPC with an active status. Because the resource property for the adapter family is named ‘adapter-family’, it is not suitable as a Python variable name. Therefore, the caller can specify the filter argument only as a parameter dictionary:
filter_args = {'adapter-family': 'osa', 'status': 'active'} active_osa_adapters = cpc.adapters.findall(**filter_args)
- find(**filter_args)[source]
Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g. for a CPC, a
Cpc
object is returned).Any resource property may be specified in a filter argument. For details about filter arguments, see Filtering.
The zhmcclient implementation handles the specified properties in an optimized way: Properties that can be filtered on the HMC are actually filtered there (this varies by resource type), and the remaining properties are filtered on the client side.
If the “name” property is specified as the only filter argument, an optimized lookup is performed that uses a name-to-URI cache in this manager object. This this optimized lookup uses the specified match value for exact matching and is not interpreted as a regular expression.
Authorization requirements:
see the list() method in the derived classes.
- Parameters
**filter_args – All keyword arguments are used as filter arguments. Specifying no keyword arguments causes no filtering to happen. See the examples for usage details.
- Returns
Resource object in scope of this manager object that matches the filter arguments. This resource object has a minimal set of properties.
- Raises
NotFound – No matching resource found.
NoUniqueMatch – More than one matching resource found.
- Raises
Exceptions raised by the list() methods in derived resource manager classes (see Reference: Resources).
Examples:
The following example finds a CPC by its name. Because the ‘name’ resource property is also a valid Python variable name, there are two ways for the caller to specify the filter arguments for this method:
As named parameters:
cpc = client.cpcs.find(name='CPC001')
As a parameter dictionary:
filter_args = {'name': 'CPC0001'} cpc = client.cpcs.find(**filter_args)
The following example finds a CPC by its object ID. Because the ‘object-id’ resource property is not a valid Python variable name, the caller can specify the filter argument only as a parameter dictionary:
filter_args = {'object-id': '12345-abc...de-12345'} cpc = client.cpcs.find(**filter_args)
- list(full_properties=False, filter_args=None)[source]
Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g. for CPCs, a list of
Cpc
objects is returned).Any resource property may be specified in a filter argument. For details about filter arguments, see Filtering.
The zhmcclient implementation handles the specified properties in an optimized way: Properties that can be filtered on the HMC are actually filtered there (this varies by resource type), and the remaining properties are filtered on the client side.
At the level of the
BaseManager
class, this method defines the interface for the list() methods implemented in the derived resource classes.Authorization requirements:
see the list() method in the derived classes.
- Parameters
- Returns
List of resource objects in scope of this manager object that match the filter arguments. These resource objects have a set of properties according to the full_properties parameter.
- Raises
Exceptions raised by the list() methods in derived resource manager classes (see Reference: Resources).
Examples:
The following example finds those OSA adapters in cage ‘1234’ of a given CPC, whose state is ‘stand-by’, ‘reserved’, or ‘unknown’:
filter_args = { 'adapter-family': 'osa', 'card-location': '1234-.*', 'state': ['stand-by', 'reserved', 'unknown'], } osa_adapters = cpc.adapters.list(full_properties=True, filter_args=filter_args)
The returned resource objects will have the full set of properties.
- find_by_name(name)[source]
Find a resource by name (i.e. value of its ‘name’ resource property) and return its Python resource object (e.g. for a CPC, a
Cpc
object is returned).This method performs an optimized lookup that uses a name-to-URI mapping cached in this manager object.
This method is automatically used by the
find()
andfindall()
methods, so it does not normally need to be used directly by users.Authorization requirements:
see the list() method in the derived classes.
- Parameters
name (string) – Name of the resource (value of its ‘name’ resource property). Regular expression matching is not supported for the name for this optimized lookup.
- Returns
Resource object in scope of this manager object that matches the filter arguments. This resource object has a minimal set of properties.
- Raises
NotFound – No matching resource found.
- Raises
Exceptions raised by the list() methods in derived resource manager classes (see Reference: Resources).
Examples:
The following example finds a CPC by its name:
cpc = client.cpcs.find_by_name('CPC001')
- find_local(name, uri, properties=None)[source]
Return a local resource object without fetching it from the HMC.
The resource object is fully functional, for example it has the proper parent resource object set and its properties can be fetched using
pull_full_properties()
.If the resource object is in the name-to-URI cache, it is returned from there, and dependent on the history it may have a minimal set of properties or the full set of properties. Otherwise, a new resource object is constructed locally from the specified name, uri and properties parameters. That resource object is not put into the name-to-URI cache because there was no validation that the specified properties are up to date or even valid at all.
- Parameters
name (string) – Name of the resource. Must not be None.
uri (string) – Object URI of the resource. Must not be None.
properties (dict) – Additional properties. Only used when the resource is not found in the name-to-URI cache. It is the responsibility of the user to ensure that the properties are valid.
- Returns
Resource object.
- flush()[source]
Invalidate the Name-URI cache of this manager.
Deprecated: This method is deprecated and using it will cause a
exceptions.DeprecationWarning
to be issued. Useinvalidate_cache()
instead.
Base definitions for resource classes.
Resource objects represent the real manageable resources in the systems managed by the HMC.
- class zhmcclient.BaseResource(manager, uri, name, properties)[source]
Abstract base class for resource classes (e.g.
Cpc
) representing manageable resources.It defines the interface for the derived resource classes, and implements methods that have a common implementation for the derived resource classes.
Objects of derived resource classes are representations of the actual manageable resources in the HMC or in systems managed by the HMC.
Objects of derived resource classes should not be created by users of this package by simply instantiating the derived resource classes. Instead, such objects are created by this package and are returned to the user as a result of methods such as
find()
orlist()
. For this reason, the __init__() method of this class and of its derived resource classes are considered internal interfaces and their parameters are not documented and may change incompatibly.- property properties
The properties of this resource that are currently present in this Python object, as a dictionary.
Key: Name of the property.
Value: Value of the property.
The returned
immutable_views.DictView
object is an immutable dictionary view that behaves like a standard Pythondict
except that it prevents any modifications to the dictionary.See the respective ‘Data model’ sections in the HMC API book for a description of the resources along with their properties.
The dictionary contains either the full set of resource properties, or a subset thereof, or can be empty in some cases.
Because the presence of properties in this dictionary depends on the situation, the purpose of this dictionary is only for iterating through the resource properties that are currently present.
Specific resource properties should be accessed via:
The resource name, via the
name
attribute.The resource URI, via the
uri
attribute.Any resource property, via the
get_property()
orprop()
methods.
Updates to property values can be done via the
update_properties()
method of the resource class. Which properties can be updated is indicated with the ‘w’ qualifier in the data model of the resource in the HMC API book.If auto-update is enabled for the resource object and the session is enabled for auto-updating as well, the property values in the returned
immutable_views.DictView
object will change as they change on the HMC.
- property uri
The canonical URI path of the resource. Will not be None.
Example:
/api/cpcs/12345
- Type
string
- property name
The name of the resource. Will not be None.
The resource name is unique across its sibling resources of the same type and with the same parent resource.
Accessing this property will cause the properties of this resource object to be updated from the HMC, if it does not yet contain the property for the resource name.
- Type
string
- property manager
Subclass of
BaseManager
: Manager object for this resource (and for all resources of the same type in the scope of that manager). Will not be None.
- property full_properties
A boolean indicating whether or not the resource properties in this object are the full set of resource properties.
Note that listing resources and creating new resources produces objects that have less than the full set of properties.
- property properties_timestamp
The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).
- pull_full_properties()[source]
Retrieve the full set of resource properties and cache them in this object.
This method serializes with other methods that access or change properties on the same Python object.
Authorization requirements:
Object-access permission to this resource.
- Raises
- get_property(name)[source]
Return the value of a resource property.
If the resource property is not cached in this object yet, the full set of resource properties is retrieved and cached in this object, and the resource property is again attempted to be returned.
This method serializes with other methods that access or change properties on the same Python object.
Authorization requirements:
Object-access permission to this resource.
- prop(name, default=None)[source]
Return the value of a resource property, applying a default if it does not exist.
If the resource property is not cached in this object yet, the full set of resource properties is retrieved and cached in this object, and the resource property is again attempted to be returned.
This method serializes with other methods that access or change properties on the same Python object.
Authorization requirements:
Object-access permission to this resource.
- Parameters
- Returns
The value of the resource property.
- Raises
- get_properties_local(names, defaults=None)[source]
Return the values of a set of resource properties, using default values for those that are not present in this Python object, without retrieving them from the HMC.
This method serializes with other methods that access or change properties on the same Python object.
- Parameters
names (string or list/tuple of strings) – Single name or list/tuple of names of the resource properties, using the names defined in the respective ‘Data model’ sections in the HMC API book.
defaults – Single value or list/tuple of values to be used as a default for resource properties that are not present. If a single value, it is used for all properties that are not present. If a list/tuple, it must be index-correlated with the names list/tuple.
- Returns
Single value (if names is a single value) or list of values (if names is a list/tuple of values) of the properties, with defaults applied.
- update_properties_local(properties)[source]
Update the values of a set of resource properties on this Python object without propagating the updates the HMC.
If a property to be updated is not present in the Python object, it is added.
This method serializes with other methods that access or change properties on the same Python object.
- __str__()[source]
Return a human readable string representation of this resource.
This method serializes with other methods that access or change properties on the same Python object.
Example result:
Cpc(name=P0000S12, object-uri=/api/cpcs/f1bc49af-f71a-3467-8def-3c186b5d9352, status=service-required)
- __repr__()[source]
Return a string with the state of this resource, for debug purposes.
This method serializes with other methods that access or change properties on the same Python object.
Note that the derived resource classes that have child resources have their own
__repr__()
methods, because only they know which child resources they have.
- auto_update_enabled()[source]
Return whether auto-update is currently enabled for the resource object.
- Returns
Indicates whether auto-update is enabled.
- Return type
- enable_auto_update()[source]
Enable auto-update for this resource object, if currently disabled.
When enabling auto-update, the session to which this resource belongs is subscribed for auto-updating if needed (see
subscribe_auto_update()
), the resource object is registered with the session’s resource updater viaregister_object()
, and all properties of this resource object are retrieved usingpull_full_properties()
in order to have the most current values as a basis for the future auto-updating.
- disable_auto_update()[source]
Disable auto-update for this resource object, if currently enabled.
When disabling auto-update, the resource object is unregistered from the session’s resource updater via
unregister_object()
, and the session is unsubscribed from auto-updating if the resource updater has no more objects registered.
Glossary
This documentation uses a few special terms:
- HMC
Hardware Management Console; the node the zhmcclient talks to.
- session-id
an opaque string returned by the HMC as the result of a successful logon, for use by subsequent operations instead of credential data. The HMC gives each newly created session-id a lifetime of 10 hours, and expires it after that.
- fulfillment
The act of satisfying requests for creation, modification, or deletion of storage volumes in a storage subsystem (i.e. of the actual storage backing a storage volume object).
Storage volume objects have a fulfillment state indicating whether the volume is fulfilled, which means that the request for creation or modification has been carried out and the state of the backing volume is now in sync with the storage volume object.
Storage group objects also have a fulfillment state indicating whether all of its storage volumes are fulfilled.
Special type names
This documentation uses a few special terms to refer to Python types:
- string
a unicode string or a byte string
- unicode string
a Unicode string type (
unicode
in Python 2, andstr
in Python 3)- byte string
a byte string type (
str
in Python 2, andbytes
in Python 3). Unless otherwise indicated, byte strings in this package are always UTF-8 encoded.- number
one of the number types
int
,long
(Python 2 only), orfloat
.- integer
- timestamp
a Timestamp-typed value as used in the HMC API. This is a non-negative integer value representing a point in time as milliseconds since the UNIX epoch (1970-01-01 00:00:00 UTC), or the value -1 to indicate special treatment of the value.
- json object
a
dict
object that is a Python representation of a valid JSON object. See py-to-json-table for details.- header dict
a
dict
object that specifies HTTP header fields, as follows:- callable
a type for callable objects (e.g. a function, calling a class returns a new instance, instances are callable if they have a
__call__()
method).- DeprecationWarning
a standard Python warning that indicates the use of deprecated functionality. See section Deprecations for details.
- HMC API version
an HMC API version, as a tuple of (api_major_version, api_minor_version), where:
Resource model
This section lists the resources that are available at the HMC API.
The term resource in this documentation is used to denote a managed object in the system. The result of retrieving a resource through the HMC API is termed a resource representation. Python classes for resources are termed to represent a resource.
For resources within a CPC, this section covers CPCs in DPM mode and classic mode, but omits any resources that are available only in ensemble mode. See section CPCs for a definition of the CPC modes.
Some of the items in this section are qualified as short terms. They are not separate types of resources, but specific usages of resources. For example, “storage adapter” is a short term for the resource “adapter” when used for attaching storage.
Resources scoped to the HMC
- Console
The HMC itself.
- Group
TBD - Not yet supported.
- Hardware Message
TBD - Not yet supported.
Also scoped to CPCs in any mode.
- Job
The execution of an asynchronous HMC operation.
- LDAP Server Definition
The information in an HMC about an LDAP server that may be used for HMC user authorization purposes.
- Metrics Context
A user-created definition of metrics that can be retrieved.
- Password Rule
A rule which HMC users need to follow when creating a HMC logon password.
- Session
A session between a client of the HMC API and the HMC.
- Task
An action that an HMC user with appropriate authority can perform.
- User
An HMC user.
- User Pattern
A pattern for HMC user IDs that are not defined on the HMC as users but can be verified by an LDAP server for user authentication.
- User Role
An authority role which can be assigned to one or more HMC users.
Resources scoped to CPCs in any mode
Resources scoped to CPCs in DPM mode
- Accelerator Adapter
Short term for an Adapter providing accelerator functions (e.g. the z Systems Enterprise Data Compression (zEDC) adapter for data compression).
- Adapter
A physical adapter card (e.g. OSA-Express adapter, Crypto adapter) or a logical adapter (e.g. HiperSockets switch).
For details, see section Adapters.
- Adapter Port
Synonym for Port.
- Capacity Group
TBD - Not yet supported.
- Crypto Adapter
Short term for an Adapter providing cryptographic functions.
- FCP Adapter
Short term for a Storage Adapter supporting FCP (Fibre Channel Protocol).
- FCP Port
Short term for a Port of an FCP Adapter.
- HBA
A logical entity that provides a Partition with access to external storage area networks (SANs) through an FCP Adapter.
For details, see section HBAs.
HBA resource objects only exist when the “dpm-storage-management” feature is not enabled. See section Storage Groups for details.
- Network Adapter
Short term for an Adapter for attaching networks (e.g. OSA-Express adapter).
- Network Port
Short term for a Port of a Network Adapter.
- NIC
Network Interface Card, a logical entity that provides a Partition with access to external communication networks through a Network Adapter.
For details, see section NICs.
- Partition
A subset of the hardware resources of a CPC in DPM mode, virtualized as a separate computer.
For details, see section Partitions.
- Port
The physical connector port (jack) of an Adapter.
For details, see section Ports.
- Storage Adapter
Short term for an Adapter for attaching storage.
- Storage Group
A grouping entity for a set of FCP or ECKD (=FICON) storage volumes. A storage group can be attached to a partition which will cause its storage volumes to be attached to the partition.
Storage Group objects exist only when the “dpm-storage-management” feature is enabled on the CPC. For details, see section Storage Groups.
- Storage Group Template
A template for Storage Groups.
- Storage Port
Short term for a Port of a Storage Adapter.
- Storage Volume
An FCP or ECKD (=FICON) storage volume defined in context of a storage group. The life cycle of a storage volume includes being defined but not fulfilled, being fulfilled but not attached, and finally being attached to a partition.
Storage Volume objects exist only when the “dpm-storage-management” feature is enabled on the CPC. For details, see section Storage Groups.
- Storage Volume Template
A template for Storage Volumes.
- vHBA
Synonym for HBA. In this resource model, HBAs are always virtualized because they belong to a Partition. Therefore, the terms vHBA and HBA can be used interchangeably.
- Virtual Function
A logical entity that provides a Partition with access to an Accelerator Adapter.
For details, see section Virtual Functions.
- Virtual Storage Resource
A representation of a storage-related z/Architecture device in a partition. For FCP type storage volumes, a Virtual Storage Resource object represents an HBA through which the attached storage volume is accessed. For FICON (ECKD) type storage volumes, a Virtual Storage Resource object represents the attached storage volume itself.
Virtual Storage Resource objects exist only when the “dpm-storage-management” feature is enabled on the CPC. For details, see section Storage Groups.
- Virtual Switch
A virtualized networking switch connecting NICs with a Network Port.
For details, see section Virtual Switches.
- vNIC
Synonym for NIC. In this resource model, NICs are always virtualized because they belong to a Partition. Therefore, the terms vNIC and NIC can be used interchangeably.
Resources scoped to CPCs in classic (and ensemble) mode
- Activation Profile
A general term for specific types of activation profiles:
- Group Profile
TBD
- Image Activation Profile
A specific Activation Profile that defines characteristics of an LPAR.
- Load Activation Profile
A specific Activation Profile that defines an operating system image that can be loaded (booted) into an LPAR.
- Logical Partition
- LPAR
A subset of the hardware resources of a CPC in classic mode (or ensemble mode), virtualized as a separate computer.
For details, see section LPARs.
- Reset Activation Profile
A specific Activation Profile that defines characteristics of a CPC.
Bibliography
- X.509
- RFC2616
IETF RFC2616, Hypertext Transfer Protocol - HTTP/1.1, June 1999
- RFC2617
IETF RFC2617, HTTP Authentication: Basic and Digest Access Authentication, June 1999
- RFC3986
IETF RFC3986, Uniform Resource Identifier (URI): Generic Syntax, January 2005
- RFC6874
- HMC API
The Web Services API of the z Systems Hardware Management Console, described in the following books:
- HMC API 2.11.1
IBM SC27-2616, System z Hardware Management Console Web Services API (Version 2.11.1)
- HMC API 2.12.0
IBM SC27-2617, System z Hardware Management Console Web Services API (Version 2.12.0)
- HMC API 2.12.1
IBM SC27-2626, System z Hardware Management Console Web Services API (Version 2.12.1)
- HMC API 2.13.0
IBM SC27-2627, z Systems Hardware Management Console Web Services API (Version 2.13.0)
- HMC API 2.13.1
IBM SC27-2634, z Systems Hardware Management Console Web Services API (Version 2.13.1)
- HMC API 2.14.0
IBM SC27-2636, IBM Z Hardware Management Console Web Services API (Version 2.14.0)
- HMC API 2.14.1
IBM SC27-2637, IBM Z Hardware Management Console Web Services API (Version 2.14.1)
- HMC API 2.15.0
IBM SC27-2638, IBM Z Hardware Management Console Web Services API (Version 2.15.0) (covers both GA1 and GA2)
- HMC Operations Guide
The operations guide of the z Systems Hardware Management Console, in the following books (subset):
- HMC Operations Guide 2.11.1
IBM SC28-6905, System z Hardware Management Console Operations Guide (Version 2.11.1)
- HMC Operations Guide 2.12.1
System z Hardware Management Console Operations Guide (Version 2.12.1)
- HMC Operations Guide 2.13.1
z Systems Hardware Management Console Operations Guide (Version 2.13.1)
- HMC Operations Guide 2.14.1
Hardware Management Console Operations Guide (Version 2.14.1)
- HMC Operations Guide 2.15.0
Hardware Management Console Operations Guide (Version 2.15.0) (covers both GA1 and GA2)
- HMC Security
Change log
Version 1.1.1
Released: 2022-02-17
Bug fixes:
Fixed an issue that delete() of element objects e.g. NICs, HBAs, VFs, storage volumes, storage template volumes) did not update the uris list in the local properties of its parent object.
Fixed the issue that ‘StorageVolumeTemplate.delete()’ provided an incorrect field in the request to the HMC. (issue #900)
Fixed issues in the zhmcclient_mock support for the “Update LPAR Properties” operation. (issue #909)
Cleanup:
Removed the ability to build the Windows executable, triggered by the fact that the corresponding build command has been removed in Python 3.10. The Windows executable has never been part of the zhmcclient package on Pypi, and building it seems odd anyway. (issue #865)
Version 1.1.0
This version contains all fixes up to version 1.0.3.
Released: 2021-11-18
Bug fixes:
Fixed maturity level from 4 (Beta) to 5 (Production/Stable).
Fixed an issue in ‘Lpar.stop()’ where incorrectly an empty body was sent, and an incorrect status has been waited for.
Fixed a TypeError in ‘Partition.mount_iso_image()’. (issue #833)
Fixed install error of wrapt 1.13.0 on Python 2.7 on Windows due to lack of MS Visual C++ 9.0 on GitHub Actions, by pinning it to <1.13.
Fixed Sphinx doc build error on Python 2.7.
Docs: Fixed description of Client.get_inventory().
Dev: Excluded more-itertools 8.11.0 on Python 3.5.
Enhancements:
Added support for the ‘Set Auto-Start List’ operation on CPCs by adding a method ‘Cpc.set_auto_start_list()’, and the corresponding mock support. (issue #472)
Improved the log entries when file-like objects are passed to ‘Partition.mount_iso_image()’.
Changed the ‘User-Agent’ header sent with each HTTP request to show ‘python-zhmcclient/<version>’.
Added support for ‘Cpc.import_dpm_configuration()’. (issue #851)
Added support for ‘Cpc.export_dpm_configuration()’.
Added a new exception classs ‘ConsistencyError’ that indicates consistency errors that should be reported.
Added a new example script examples/export_dpm_config.py.
Cleanup:
Defined HMC resource class names centrally.
Version 1.0.0
This version contains all fixes up to version 0.32.1.
Released: 2021-08-05
Incompatible changes:
Dropped support for Python 3.4. Python 3.4 has had its last release as 3.4.10 on March 18, 2019 and has officially reached its end of life as of that date. Current Linux distributions no longer support Python 3.4. (issue #792)
Bug fixes:
Fixed an install error of lazy-object-proxy on Python 3.5 by no longer installing pylint/astroid/typed-ast/lazy-object-proxy on Python 3.5. It was already not invoked anymore on Python 3.5, but still installed.
Increased minimum version of Pylint to 2.5.2 on Python 3.6 and higher.
Fixed a bug where ‘Console.list_permitted_partitions()’ and ‘Console.list_permitted_lpars()’ when run on HMC/SE version 2.14.0 failed when accessing the ‘se-version’ property of the partition unconditionally. That property was introduced only in HMC/SE version 2.14.1. (issue #816)
Enhancements:
Made read and write access to the properties dictionary of zhmcclient resource objects thread-safe by adding a Python threading.RLock on each resource object.
Added support for auto-updating of resources. For details, see the new section ‘Concepts -> Auto-updating of resources’. (issue #762)
Cleanup:
Removed old build tools that were needed on Travis and Appveyor (remove_duplicate_setuptools.py and retry.bat) (issue #809)
Version 0.32.0
This version contains all fixes up to version 0.31.1.
Released: 2021-07-02
Bug fixes:
Docs: Fixed and added missing authorization requirements for the Partition and Lpar methods.
Examples: Fixed errors in and improved metrics examples.
Fixed issues raised by new Pylint version 2.9.1.
Enhancements:
Added support for ‘Console.list_permitted_partitions()’ and ‘Console.list_permitted_lpars()’. These methods require HMC 2.14.0 or later. (issue #793)
The Console object returned by ‘client.consoles.console’ is now a locally built object in order to avoid needless property retrieval.
Version 0.31.0
This version contains all fixes up to version 0.30.2.
Released: 2021-06-10
Incompatible changes:
Method ‘NotificationReceiver.notifications()’ now raises JMS errors returned by the HMC as a new exception ‘NotificationJMSError’. JSON parse errors are now raised as a new exception ‘NotificationParseError’. Both new exceptions are based on a new base exception ‘NotificationError’. (issue #770)
By default, the zhmcclient now verifies the HMC certificate using the CA certificates in the Python ‘certifi’ package. This can be controlled with a new ‘verify_cert’ init parameter to the ‘zhmcclient.Session’ class. (issue #779)
The ‘properties’ attribute of the resource classes (e.g. ‘Partition’) now is an immutable ‘DictView’ object in order to enforce the stated rule that that callers must not modify the properties dictionary. If your code used to make such modifications nevertheless, it will now get a ‘TypeError’ or ‘AttributeError’ exception, dependent on the nature of the modification.
Bug fixes:
Fixed a missing argument in ‘NotificationListener.on_message()’ by pinning stomp.py such that 6.1.0 and 6.1.1 are excluded. (issue #763)
Fixed a package dependency issue when setting up the development environment with the “pywinpty” package on Python 2.7 and Windows. (issue #772)
JMS errors returned by the HMC are now handled by raising a new exception ‘NotificationJMSError’ in the ‘NotificationReceiver.notifications()’ method. Previously, an exception was raised in the thread running the notification receiver, rendering it unusable after that had happened. (issue #770)
Fixed a TypeError for concatenating str and bytes. (issue #782)
Enhancements:
Added a ‘verify_cert’ init parameter to the ‘zhmcclient.Session’ class to enable verification of the server certificate presented by the HMC during SSL/TLS handshake. By default, the certificate is validated against the CA certificates provided in the Python ‘certifi’ package. (issue #779)
Added catching of OSError/IOError exceptions raised by the ‘requests’ package for certain certificate validation failures, re-raising such exceptions as a pywbem.ConnectionError.
Docs: Added a section “Security” to the documentation that describes security related aspects in the communication between the zhmcclient and the HMC. (related to issue #779)
Docs: Added a section “Troubleshooting” to appendix of the documentation that currently lists two cases of communication related issues. (related to issue #779)
The ‘properties’ attribute of the resource classes (e.g. ‘Partition’) now is an immutable ‘DictView’ object provided by the ‘immutable-views’ package, in order to enforce the stated rule that that callers must not modify the properties dictionary of resource objects.
Version 0.30.0
Released: 2021-04-06
Bug fixes:
Docs: Properties of classes are now shown in the Attributes summary table of the class. (issue #726)
Docs: Fixed the incorrect default value documented for the force parameter of Lpar.scsi_load(). The correct default is False. (part of issue #748).
Fixed StatusTimeout when activating an LPAR that goes straight to status “operating”, by adding “operating” as a valid target value for the operational status. (issue #755)
Enhancements:
Added an optional parameter secure_boot to Lpar.scsi_load() (issue #748).
Added an optional parameter force to Lpar.scsi_dump() (issue #748).
Version 0.29.0
Released: 2021-03-23
Bug fixes:
Mitigated the coveralls HTTP status 422 by pinning coveralls-python to <3.0.0.
Docs: Removed outdated reference to KVM for IBM z Systems Admin book that was used as a second example in the Introduction section.
Docs: Added the missing Methods and Attributes tables to the description of resources related to the storage management feature (e,g. StorageGroup). (issue #708)
Enhancements:
Added a new Partition.start_dump_program() method that performs the HMC operation ‘Start Dump Program’. That operation is supported on CPCs in DPM mode that have the DPM storage management feature (i.e. z14 and later) and complements the ‘Dump Partition’ HMC operation that is supported only on CPCs in DPM mode that do not have the DPM storage management feature (i.e. z13 and earlier). Mock support for the ‘Start Dump Program’ operation was also added. (issue #705).
Improved zhmcclient HMC logging in error cases by not truncating the HTTP response content for HTTP status 400 and higher. (issue #717) Also the truncation limit was icreased to 30000 to accomodate most HMC responses.
Improved display of zhmcclient.HTTPError exceptions by adding the ‘stack’ field if present. (issue #716)
Suppressed exceptions that were caught and a new exception was raised in the except clause, by setting __cause__ = None on the new exception. This avoids lengthy and unnecessary tracebacks that contain the message ‘Another exception occurred when handling …’. (issue #715)
Improved the handling of resource not found errors during metrics processing by adding a new zhmcclient.MetricsResourceNotFound exception that may now be raised when accessing the MetricObjectValues.resource property. (zhmc-prometheus-exporter issue #113)
Blanked out value of ‘x-api-session’ field (Session ID) when logging error responses. (zhmccli issue #136)
Added support for Capacity Groups in DPM mode, by adding resource classes zhmcclient.CapacityGroup and zhmcclient.CapacityGroupManager and a property zhmcclient.Cpc.capacity_groups for accessing them. (issue #734)
Cleanup:
Docs: Moved change log up one level to avoid Sphinx warning about duplicate labels.
Version 0.28.0
Released: 2020-12-20
Incompatible changes:
Removed the installed scripts cpcdata and cpcinfo and added them as cpcdata.py and cpcinfo.py to the examples folder.
Bug fixes:
Test: Increased time tolerance for time-based tests.
Docs: Added z15 to supported environments (issue #684).
Fixed an AttributeError in UserPatternManager.reorder() (related to issue #661).
Test: Fixed an AttributeError in test utilities class HMCDefinition (related to issue #661).
Test: Fixed incorrect assignment in adapter test (related to issue #661).
Enhancements:
Migrated from Travis and Appveyor to GitHub Actions. This required several changes in package dependencies for development.
Added support for operations for managing temporary processor capacity: Cpc.add_temporary_capacity() and Cpc.remove_temporary_capacity().
Added support for status timeout in Partition.stop() that waits for partition stop to reach desired status.
Test: Resolved remaining Pylint issues and enforcing no issues from now on (issue #661).
Version 0.27.0
Released: 2020-09-10
This version contains all fixes up to 0.26.2.
Bug fixes:
Fixed Travis setup by removing circumventions for old issues that caused problems meanwhile.
Adjusted versions of dependent packages for development environment to fix issues on Python 3.4.
Fixed AttributeError when calling partition.list_attached_storage_groups(). (See issue #629)
Docs: Fixed description to start a new version that was missing updating the version to the new development version. (See issue #639)
Docs: Fixed description of installation from a repo branch. (See issue #638)
Test: Fixed missing ffi.h file on CygWin when testing (See issue #655)
Docs: Fixed links to HMC WS API books that have become invalid. (See issue #665)
Fixed empty port list returned by PortManager.list() for CNA adapters.
Install: Fixed the broken installation from the source distribution archive on Pypi (see issue #651)
Test: Pinned ‘pyrsistent’ package (used by jupyter notebook) to <0.16.0 on Python 2.7 and to <0.15.0 on Python 3.4.
Test: Fixed issue where virtualenv on pypy3 created env one level higher. (see issue #673)
Enhancements:
Added an easy way to print debug information for inclusion into issues, via python -m zhmcclient.debuginfo. (See issue #640)
Added discover_fcp() and get_connection_report() methods to the StorageGroup resource. Added an example discover_storage_group.py that uses the two new methods. (See issue #623)
Test: Running coveralls for all Python versions in order to cover Python version-specific code. The coveralls.io web site consolidates these runs properly into a single result.
Docs: Added links to HMC WS APi and Operations books for z15. (Related to issue #665)
Added the z15 machine types 8561 and 8562 for detecting the maximum number of partitions, and started exploiting the new ‘maximum-partitions’ property of the CPC for this purpose.
Cleanup
Docs: Removed link to “KVM for IBM z Systems - System Administration” book, because the product is no longer supported. (Related to issue #665)
Changed the theme of the documentation on RTD from classic to sphinx_rtd_theme (See issue #668)
Test: Added ‘make installtest’ to the Makefile to test installation of the package into an empty virtualenv using all supported installation methods. Added these install tests to the Travis CI tests. (related to issue #651)
Version 0.26.0
Released: 2020-01-24
This version contains all changes from 0.25.1.
Bug fixes:
Added the missing os_ipl_token parameter to Lpar.scsi_dump().
Migrated from using the yamlordereddictloader package to using the yamlloader package, because yamlordereddictloader got deprecated. (See issue #605)
Pinned version of PyYAML to <5.3 for Python 3.4 because 5.3 removed support for Python 3.4
Increased minimum version of stomp.py to 4.1.23 to pick up a fix for hangs during NotificationReceiver.close(). (See issue #572)
Enhancements:
Promoted the development status of the zhmcclient package on Pypi from 3 - Alpha to 4 - Beta.
Added support for Python 3.8 to the package metadata and to the Travis and Appveyor and Tox environments. (See issue #596)
Dropped the use of the pbr package. The package version is now managed in zhmcclient/_version.py. (See issue #594)
Test: Added support for TESTOPTS env var to Makefile to be able to specify py.test options when invoking make test.
Version 0.25.0
Released: 2019-12-18
Bug fixes:
Docs: Fixed incorrect statement about HMC version 2.14.0 supporting both GA generations of z14 machines.
Enhancements:
Docs: Added HMC version 2.14.1 in “Bibliography” and “Introduction” sections.
Added support for following LPAR operations:
Lpar.psw_restart() (HMC: “PSW Restart”)
Lpar.scsi_dump() (HMC: “SCSI Dump”)
Added support for Storage Template objects in DPM mode (see issue #589).
Version 0.24.0
Released: 2019-08-15
Incompatible changes:
Operations that resulted in HTTP status 403, reason 1 (“The user under which the API request was authenticated does not have the required authority to perform the requested action.”) so far raised ServerAuthError. However, that exception does not represent that situation properly, because the login user is actually properly authenticated. The handling of this case was changed to now raise HTTPError instead of ServerAuthError. This change is only incompatible to users of the zhmcclient API who have code handling this exception specifically.
Bug fixes:
Fixed LookupError on unknown encoding ISO-5589-1 in test_session.py test that occurred with latest requests_mock package.
Increased minimum version of flake8 to 3.7.0 due to difficulties with recognizing certain ‘noqa’ statements. This required explicitly specifying its dependent pycodestyle and pyflakes packages with their minimum versions, because the dependency management did not work with our minimum package versions.
Fixed use of incorrect HTTP method in Console.get_audit_log() and Console.get_security_log(). See issue #580.
Enhancements:
Improved end2end test support for zhmcclient and its using projects. The zhmcclient.testutils package already provides some support for end2end tests by users of the zhmcclient package. It is also used by the end2end tests of the zhmcclient package itself. This change improves that support, mainly from a perspective of projects using zhmcclient.
Improved the show_os_messages.py example.
Blanked out the session ID value in the log record for logging off.
Changed import of ‘stomp’ module used for notifications from the HMC, to be lazy, in order to speed up the import of ‘zhmcclient’ for its users. The ‘stomp’ module is now imported when the first zhmcclient.NotificationReceiver object is created. Also, only the class needed is imported now, instead of the entire module.
Added timezone support to the utility function zhmcclient.datetime_from_timestamp(). The desired timezone for the returned object can now be specified as an optional argument, defaulting to UTC for compatibility. This allows displaying HMC timestamps in local time rather than just UTC time.
Added support for specifying multiple notification topics to zhmcclient.NotificationReceiver.
Version 0.23.0
Released: 2019-04-04
Bug fixes:
Fixed the list_storage_groups.py example. It used a non-existing property on the Cpc class.
Passwords and session tokens are now correctly blanked out in logs. See issue #560.
Enhancements:
Added support for the new “Zeroize Crypto Domain” operation that allows zeroizing a single crypto domain on a crypto adapter. This operation is supported on z14 GA2 and higher, and the corresponding LinuxOne systems.
Changes in logging support:
Removed the notion of module-specific loggers from the description of the logging chapter, because that was not used at all, and is not expected to be used in the future: Errors are supposed to be raised as exceptions and not logged, and warnings are supposed to be issued as Python warnings and not logged.
Escaped newlines to blanks in log messages, so that all log messages are now on a single line.
Changed the syntax for zhmcclient.api log messages, to start with “Called:” and “Return:” instead of “==>” and “<==”.
Changed the syntax for zhmcclient.hmc log messages, to start with “Request:” and “Respons:” instead of “HMC request:” and “HMC response:”, in order to have the URLs column-adjusted.
Version 0.22.0
Released: 2019-01-07
Enhancements:
Added a mitigation for a firmware defect that causes filtering of adapters by adapter-id to return an empty result when the specified adapter-id contains hex digits (‘a’ to ‘f’). See issue #549.
Version 0.21.0
Released: 2018-10-31
Bug fixes:
Update Requests package to 2.20.0 to fix following vulnerability of the National Vulnerability Database: https://nvd.nist.gov/vuln/detail/CVE-2018-18074
Version 0.20.0
Released: 2018-10-24
Bug fixes:
Docs: Added missing support statements for the LinuxOne Emperor II machine generations to the documentation (The corresponding z14 was already listed).
Enhancements:
Docs: Streamlined, improved and fixed the description how to release a version and how to start a new version, in the development section of the documentation.
Added support for Python 3.7. This required increasing the minimum versions of several Python packages in order to pick up their Python 3.7 support:
pyzmq from 16.0.2 to 16.0.4 (While 16.0.4 works for this, only 17.0.0 declares Python 3.6(!) support on Pypi, and Python 3.7 support is not officially declared on Pypi yet for this package).
PyYAML from 3.12 to 3.13 (see PyYAML issue https://github.com/yaml/pyyaml/issues/126).
Docs: Added support statements for the z14-ZR1 and LinuxONE Rockhopper II machine generations to the documentation.
Added support for the z14-ZR1 and LinuxONE Rockhopper II machine generations to the Cpc.maximum_active_partitions() method.
Provided direct access to the (one) Console object, from the ConsoleManager and CpcManager objects, via a new console property. This is for convenience and avoids having to code find() or list() calls. The returned Console object is cached in the manager object.
Also, added a console property to the FakedConsoleManager class in the mock support, for the same purpose.
Added a property client to class CpcManager for navigating from a Cpc object back to the Client object which is the top of the resource tree.
Added support for the new concept of firmware features to Cpcs and Partitions, by adding methods feature_enabled() and feature_info() to classes Cpc and Partition for inspection of firmware features. The firmware feature concept was introduced starting with the z14-ZR1 and LinuxONE Rockhopper II machine generation. The DPM storage management feature is the first of these new firmware features.
Added support for the DPM storage management feature that is available starting with the z14-ZR1 and LinuxONE Rockhopper II machine generation. This includes new resources like Storage Groups, Storage Volumes, and Virtual Storage Resources. It also includes new methods for managing storage group attachment to Partitions. The new items in the documentation are:
In 5.1. CPCs: list_associated_storage_groups(), validate_lun_path().
In 5.5. Partitions: attach_storage_group(), detach_storage_group(), list_attached_storage_groups().
5.12. Storage Groups
5.13. Storage Volumes
5.14. Virtual Storage Resources
In 5.15 Console: storage_groups
Added support for changing the type of storage adapters between FICON and FCP, via a new method Adapter.change_adapter_type(). This capability was introduced with the z14-ZR1 and LinuxONE Rockhopper II machine generation.
Version 0.19.11
Released: 2018-05-14
Note: The version number of this release jumped from 0.19.0 right to 0.19.11, for tooling reasons.
Enhancements:
Docs: Improved the description of installation without Internet access, and considerations on system Python vs. virtual Python environments.
Lowered the minimum version requirements for installing the zhmcclient package, for the packages: requests, pbr, decorator. Added support for tolerating decorator v3.4 in the zhmcclient _logging module.
Adjusted development environment to changes in Appveyor CI environment.
Version 0.19.0
Released: 2018-03-15
Incompatible changes:
The
Lpar.deactivate()
method is now non-forceful by default, but can be made to behave like previously by specifying the newforce
parameter. In force mode, the deactivation operation is permitted when the LPAR status is “operating”.
Bug fixes:
Fixed a flawed setup of setuptools in Python 2.7 on the Travis CI, where the metadata directory of setuptools existed twice, by adding a script remove_duplicate_setuptools.py that removes the moot copy of the metadata directory (issue #434).
Fixed a bug where multiple Session objects shared the same set of HTTP header fields, causing confusion in the logon status.
Enhancements:
Migrated all remaining test cases from unittest to pytest, and started improving the testcases using pytest specific features such as parametrization.
Added support for a
force
parameter in theLpar.activate()
,Lpar.deactivate()
, andLpar.load()
methods. It controls whether the operation is permitted when the LPAR status is “operating”.Note that this changes
Lpar.deactivate()
to be non-forceful by default (force=True was hard coded before this change).Added support for an
activation_profile_name
option in theLpar.activate()
method, that allows specifying the activation profile to be used. The default is as before: The profile that is specified in thenext-activation-profile
property of theLpar
object.Made the
load_address
parameter ofLpar.load()
optional in order to support z14. Up to z13, the HMC now returns an error if no load address is specified. Adjusted the zhmcclient mock support accordingly.Added LPAR status checks in the zhmcclient mock support, so that activate, deactivate and load returns the same errors as the real system when the initial LPAR status is not permitted, or when the activation profile name does not match the LPAR name, or when no load address is specified.
Improved the testcases for the Lpar and LparManager classes.
Added the ability to mock the resulting status of the faked Lpars in the zhmcclient mock support, for the Activate, Deactivate, and Load operations. Added a new chapter “URI handlers” in section “Mock support” of the documentation, to describe this new ability.
Added support for CPC energy management operations:
Cpc.set_power_save()
(HMC: “Set CPC Power Save”)Cpc.set_power_capping()
(HMC: “Set CPC Power Capping”)Cpc.get_energy_management_properties()
(HMC: “Get CPC Energy Management Data”)
The zhmcclient package no longer adds a NullHandler to the Python root logger (but still to the zhmcclient.api/.hmc loggers).
Added a function test concept that tests against a real HMC.
Version 0.18.0
Released: 2017-10-19
Incompatible changes:
Removed the zhmc CLI support from this project, moving it into a new GitHub project
zhmcclient/zhmccli
.This removes the following prerequisite Python packages for the zhmcclient package:
click
click-repl
click-spinner
progressbar2
tabulate
prompt_toolkit (from click-repl)
python-utils (from progressbar2)
wcwidth (from prompt-toolkit -> click-repl)
Bug fixes:
Fixed a flawed setup of setuptools in Python 2.7 on the Travis CI, where the metadata directory of setuptools existed twice, by adding a script remove_duplicate_setuptools.py that removes the moot copy of the metadata directory (issue #434).
Version 0.17.0
Released: 2017-09-20
Incompatible changes:
The zhmcclient mock support for Partitions no longer allows to stop a partition when it is in status ‘degraded’ or ‘reservation-error’. That is consistent with the real HMC as described in the HMC API book.
In the HTTPError exception class, args[0] was set to the body argument, i.e. to the entore response body. Because by convention, args[0] should be a human readable message, this has been changed to now set args[0] to the ‘message’ field in the response body, or to None if not present.
Bug fixes:
Fixed the bug that aborting a confirmation question in the CLI (e.g. for “zhmc partition delete”) caused an AttributeError to be raised. It now prints “Aborted!” and in interactive mode, terminates only the current command. (issue #418).
Fixed an AttributeError when calling ‘zhmc vfunction update’. Access to a partition from nic and vfunction is done via the respective manager (issue #416).
In the zhmc CLI, fixed that creating a new session reused an existing session. This prevented switching between userids on the same HMC (issue #422).
Docs: In the “Introduction” chapter of the documentation, fixed the HMC API version shown for z14.
Docs: In the Appendix of the documentation, added IBM book number and link for the HMC API book of z14.
Enhancements:
Avoided DeprecationWarning on Python 3 for invalid escape sequences in some places.
The zhmcclient mock support for various resource classes did not always check for invalid CPC status and for invalid Partition status as described in the HMC API book. It now does.
In the mock support, invalid input to faked resource classes (mainly when adding faked resources) is now handled by raising a new exception
zhmcclient_mock.InputError
(instead ofValueError
). The URI handler of the mock support now converts that into an HTTP error 400 (Bad Request), consistent with the HMC API book.Added
datetime_from_timestamp()
anddatetime_from_timestamp()
functions that convert between Pythondatetime
objects and HMC timestamp numbers.Added mock support for Metrics resources.
Added a
verify
argument toSession.logoff()
, consistent withSession.logon()
. This was needed as part of fixing issue #422.Added a __repr__() function to the Session class, for debug purposes.
In the ParseError exception class, a message of None is now tolerated, for consistency with the other zhmcclient exception classes.
In the NotFound exception class, a filter_args parameter of None is now tolerated, for consistency with the NoUniqueMatch exception class.
Documented for the zhmcclient exception classes how args[0] is set.
Clarified in the documentation that the manager and resources parameters of the NoUniqueMatch and NotFound exception classes must not be None.
Improved the unit test cases for the Client class and for the zhmcclient exception classes, and migrated them to py.test.
Migrated the unit tests for HBAs from unittest to py.test, and improved the test cases.
In the Hba.reassign_port() method, updated the Hba object with the changed port, consistent with other update situations.
Clarified in the description of HbaManager.list() that only the ‘element-uri’ property is returned and can be used for filtering.
The mock support for the “Create NIC” operation now performs more checking on the URIs specified in the ‘network-adapter-port’ or ‘virtual-switch-uri’ input properties, raising HTTP status 404 (Not Found) as specified in the HMC API book.
In the
FakedNic.add()
method of the mock support, the checking for the URIs specified in the ‘network-adapter-port’ or ‘virtual-switch-uri’ input properties was relaxed to only the minimum, in order to make the setting up of faked resources easier.Migrated the unit tests for
Nic
andNicManager
from unittest to py.test, and improved them.Improved the way the named tuples
MetricGroupDefinition
andMetricDefinition
are documented.Added support for
Console
resource and its child resourcesUser
,User Role
,User Pattern
,Password Rule
,Task
, andLDAP Server Definition
, both for the zhmcclient API and for the zhmcclient mock support.As part of support for the
Console
resource, added a new resource classUnmanagedCpc
which representd unmanaged CPCs that have been discovered by the HMC. The existingCpc
class continues to represent only managed CPCs; this has been clarified in the documentation.As part of support for the
Console
resource, added a methodwait_for_available()
to theClient
class, which waits until the HMC is available again after a restart. This method is used byConsole.restart()
, but it can also be used by zhmcclient users.As part of support for the
Console
resource, improvedSession.post()
to allow for an empty response body when the operation returns with HTTP status 202 (Accepted). This status code so far was always assumed to indicate that an asynchronous job had been started, but it can happen in someConsole
operations as well.Improved the error information in the
ParseError
exception, by adding the “Content-Type” header in cases where that is interesting.Add CLI commmands to mount and unmount an ISO to a Partition.
Version 0.16.0
Released: 2017-08-29
Bug fixes:
Fixed CLI: Remove defaults for options for ‘partition update’ (issue #405).
Enhancements:
Added Code Climate support.
Version 0.15.0
Released: 2017-08-15
Incompatible changes:
In case the user code was specifically processing the reason code 900 used for HTML-formatted error responses with HTTP status 500: This reason code has been split up into multiple reason codes. See the corresponding item in section “Enhancements”.
Bug fixes:
Fixed a TypeError: “‘odict_values’ object does not support indexing” on Python 3.x (issue #372).
Minor fixes in the documentation (e.g. fixed name of
MetricGroupValues
class).Fixed the zhmc CLI for Python 3 where multiple commands raised AttributeError: “‘dict’ object has no attribute ‘iteritems’ in
zhmccli/_helper.py
. (issue #396).
Enhancements:
Added support for the HMC Metric Service. For details, see section ‘Metrics’ in the zhmcclient documentation. There is an example script
metrics.py
demonstrating the use of the metrics support. The metrics support caused an additional package requirement for thepytz
package.Added support for a “metrics” command to the zhmc CLI.
Added support for the IBM z14 system (in internal machine type tables and in the documentation).
zhmccli: Support for ‘authorization controls’ of a Partition (issue #380)
Added CLI support for processing weights (issue #383)
The HTTPError raised at the API for HMC Web Services not enabled now has a simple error message and uses a specific reason code of 900. Previously, the returned HTML-formatted response body was used for the message and a generic reason code of 999. All other HTML-formatted error responses still use the generic reason code 999. That reason code 999 is now documented to be changed to more specific reason codes, over time. (issue #296).
Reduced the package requirements to only the direct dependencies of this package.
Changed the experimental
Cpc.get_free_crypto_domains()
method to test only control-usage access to the specified adapters. Improved that method by supporting None for the list of adapters which means to inspect all crypto adapters of the CPC.
Version 0.14.0
Released: 2017-07-07
Incompatible changes:
Changed the return value of
TimeStatsKeeper.snapshot()
from a list of key/value tuples to a dictionary. This is more flexible and reduces the number of data structure conversions in different scenarios. See issue #269.Changed the arguments of
Partition.mount_iso_image()
incompatibly, in order to fix issue #57.
Bug fixes:
Fixed the documentation of several asynchronous
Partition
methods that incorrectly documented returningNone
in case of synchronous invocation, to now document returning an empty dictionary:Partition.start()
Partition.stop()
Partition.dump_partition()
Partition.psw_restart()
All other asynchronous methods did not have this issue. See issue #248.
Clarified in the documentation of all exceptions that have a
details
instance variable, that it is neverNone
.Fixed using ‘–ssc-dns-servers’ option for the CLI commands ‘zhmc partition create/update’. See issue #310.
Fixed the incorrect parameters of
Partition.mount_iso_image()
. See issue #57.Reads the vlan-id as a integer instead as a string for the ‘zhmc nic create/update’ cli command. See issue #337.
Fixed the AttributeError that occurred when using zhmcclient in Jupyter notebooks, or in the python interactive mode. See issue #341.
Enhancements:
Improved content of
zhmcclient.ParseError
message for better problem analysis.Increased the default status timeout from 60 sec to 15 min, in order to accomodate for some large environments. The status timeout applies to waiting for reaching the desired LPAR status after the HMC operation ‘Activate LPAR’ or ‘Deactivate LPAR’ has completed.
Allow
None
as a value for theload_parameter
argument ofLpar.load()
, and changed the default to beNone
(the latter change does not change the behavior).Added actual status, desired statuses and status timeout as attributes to the
StatusTimeout
exception, for programmatic processing by callers.In the zhmc CLI, added a
--allow-status-exceptions
option for thelpar activate/deactivate/load
commands. Setting this option causes the LPAR status “exceptions” to be considered an additional valid end status when waiting for completion of the operation.Improved documentation of CLI output formats.
Simplified the message of the
OperationTimeout
exception.Split the
AuthError
exception intoClientAuthError
andServerAuthError
that are used depending on where the authentication issue is detected. Reason for the split was that the two subclasses have different instance variables. TheAuthError
exception class is now an abstract base class that is never raised but can be used to catch exceptions.Made error data available as instance variables of the following exceptions:
ConnectTimeout
,ReadTimeout
,RetriesExceeded
,ClientAuthError
,ServerAuthError
,OperationTimeout
, andStatusTimeout
,NotFound
,NoUniqueMatch
.Improved unit test cases for
zhmcclient._exceptions
module.Added support to the zhmc CLI for an interactive session to the console of the operating system running in a partition (
zhmc partition console
) or LPAR (zhmc lpar console
).Added
str_def()
method to all exception classes, which returns a definition-style string for parsing by scripts.In the zhmc CLI, added options
-e
,--error-format
for controlling the format of error messages. The-e def
option selects the format returned by the newstr_def()
methods. This format provides for easier parsing of details of error messages by invoking scripts.Added
wait_for_status()
methods to theLpar
andPartition
classes, in order to ease the work for users that need to ensure that a particular LPAR or partition status is reached.Added support for crypto-related methods on the
Partition
andAdapter
resource classes. Added zhmcclient mock support for the faked partition (not yet for the faked adapter).Added that
Partition.start()
waits for reaching the desired status ‘active’ or ‘degraded’, because it transitions through status ‘paused’ when starting a partition.Improved the
NoUniqueMatch
exception so that the list of resources that did match the filter, are shown with their URIs in the error message, and are available as newresources
andresource_uris
attributes. This change adds a required argumentresources
to the constructor ofNoUniqueMatch
. However, since this exception is only supposed to be raised by the zhmcclient implementation, this change is compatible to zhmcclient users.Moved the invocation of PyLint from the “make check” target into its own “make pylint” target, inorder to speed up the CI testing.
Added the ability for
Session.post()
to support binary data as the payload. Thebody
argument may now be a dictionary which is represented as a JSON string, a binary string which is used directly, or a unicode string which is encoded using UTF-8. This was necessary to fix issue #57.In the zhmcclient mock support, added a Python property
name
to all faked resources, which returns the value of the ‘name’ resource property.Added a Python property
maximum_crypto_domains
to theAdapter
class, which returns the maximum number of crypto domains of a crypto adapter.Added a Python property
maximum_active_partitions
to theCpc
class, which returns the maximum number of active LPARs or partitions of a CPC.Added
get_free_crypto_domains()
method to theCpc
class, in order to find out free domain index numbers for a given set of crypto adapters. Note: This method is considered experimental in this version.Added an
update_properties()
method to theLpar
andCpc
resource classes.Improved the description of the
Hba.create()
andNic.create()
methods to describe how the backing adapter port is specified.Extended the zhmcclient mock support by adding support for all operations thet are supported at the zhmcclient API but were not yet supported for mocking, so far.
Version 0.13.0
Released: 2017-05-18
Incompatible changes:
In the CLI, changed the default for number of processors for the
zhmc partition create
command to create 1 IFL by default, if neither IFLs nor CPs had been specified. Also, a specified number of 0 processors is now passed on to the HMC (and rejected there) instead of being removed by the CLI. This keeps the logic simpler and more understandable. See also issue #258.
Deprecations:
Deprecated the
BaseManager.flush()
method in favor of the newBaseManager.invalidate_cache()
method.
Bug fixes:
Fixed that the defaults for memory for the
zhmc partition create
command were ignored (issue #246).The default values for the retry / timeout configuration for a session has been changed to disable read retries and to set the read timeout to 1 hour. In addition, read retries are now restricted to HTTP GET methods, in case the user enabled read retries. See issue #249.
Fixed that resource creation, deletion, and resource property updating now properly updates the resource name-to-URI cache in the zhmcclient that is maintained in the *Manager objects. As part of that, the BaseManager init function got an additional required argument session, but because creation of manager objects is not part of the external API, this should not affect users. See issue #253.
In the unit testcases for the update_properties() and delete() methods of resource classes, fixed incorrect assumptions about their method return values. See issue #256.
In the unit testcases for the update_properties() and delete() methods of resource classes, fixed incorrectly returned response bodies for mocked DELETE and POST (for update), and replaced that with status 204 (no content). This came up as part of fixing issue #256.
Fixed that
find(name)
raisedNotFound
for existing resources, for resource types that are elements (i.e. NICs, HBAs, VFs, Ports) (issue #264).Fixed that the filter arguments for
find()
,findall()
, andlist()
for string properties when matched on the client side are matched using regular expressions instead of exact matching, consistent with the zhmcclient documentation, and with server-side matching on the HMC. See issue #263.Fixed that the filter arguments for
find()
,findall()
, andlist()
when used with lists of match values incorrectly applied ANDing between the list items. They now apply ORing, consistent with the zhmcclient documentation, and with server-side matching on the HMC. See issue #267.Fixed that the
Cpc.dpm_enabled
property incorrectly returnedTrue
on a z13 in classic mode. See issue #277.Fixed errors in zhmcclient mock support related to DPM mode checking.
Fixed that filter arguments specifying properties that are not on each resource, resulted in raising KeyError. An example was when the “card-location” property was specified when finding adapters; that property does not exist for Hipersocket adapters, but for all other types. This situation is now handled by treating such resources as non-matching. See issue #271.
Fix when providing ‘load-parameter’ option. See issue #273
Enhancements:
Added content to the “Concepts” chapter in the documentation.
The update_properties() method of all Python resource objects now also updates the properties of that Python resource object with the properties provided by the user (in addition to issuing the corresponding Update Properties HMC operation. This was done because that is likely the expectation of users, and we already store user-provided properties in Python resource objects when creating resources so it is now consistent with that. This came up as part of issue #253.
As part of fixing the name-to-URI cache, a new attribute name_uri_cache_timetolive was added to class RetryTimeoutConfig, which allows controlling after what time the name-to-URI cache is automatically invalidated. The default for that is set in a new DEFAULT_NAME_URI_CACHE_TIMETOLIVE constant. Also, the *Manager classes now have a new method invalidate_cache() which can be used to manually invalidate the name-to-URI cache, for cases where multiple parties (besides the current zhmcclient instance) change resources on the HMC. This came up as part of issue #253.
Improved the documentation of the lookup methods (list(), find(), findall()) and of the resource filtering concept in section ‘Filtering’. Related to issue #261.
Added zhmcclient mock support for the Create Hipersocket and Delete Hipersocket operations.
Added support for filtering in the zhmcclient mock support.
In order to improve the ability to debug the resource and manager objects at the API and the faked resource and manager objects of the mock support, the
__repr()__
methods ahave been improved. Because these functions now display a lot of data, and because testing their string layout is not very interesting, all unit test cases that tested the result of__repr()__
methods have been removed.Add basic Secure Service Container support to the CLI.
Version 0.12.0
Released: 2017-04-13
Incompatible changes:
The password retrieval function that can optionally be passed to
Session()
has changed its interface; it is now being called with host and userid. Related to issue #225.
Bug fixes:
Added WWPN support in mocking framework (issue #212).
Fixed error in mock support where the operation_timeout argument to FakedSession.post() was missing.
Fixed a bug in the unit test for the mock support, that caused incomplete expected results not to be surfaced, and fixed the incomplete testcases.
Fixed in the CLI that the spinner character was part of the output.
Improved robustness of timestats tests by measuring the actual sleep time instead of going by the requested sleep time.
Added support for ‘error’ field in ‘job-results’ (fixes issue #228).
Fixed version mismatches in CI test environment when testing with the minimum package level by consistently using the latest released packages as of zhmcclient v0.9.0 (2016-12-27). This caused an increase in versions of packages needed for the runtime.
Enhancements:
Improved the mock support by adding the typical attributes of its superclass FakedBaseResource to the FakedHmc class.
Improved the mock support by adding __repr__() methods to all Faked* classes that return an object representation suitable for debugging.
In the mock support, the following resource properties are now auto-set if not specified in the input properties:
Cpc:
‘dpm-enabled’ is auto-set to False, if not specified.
‘is-ensemble-member’ is auto-set to False, if not specified.
‘status’ is auto-set, if not specified, as follows: If the ‘dpm-enabled’ property is True, it is set to ‘active’; otherwise it is set to ‘operating’.
Partition: ‘status’ is auto-set to ‘stopped’, if not specified.
Lpar: ‘status’ is auto-set to ‘not-activated’, if not specified.
Adapter: ‘status’ is auto-set to ‘active’, if not specified.
In the CLI, added
-y
as a shorter alternative to the existing--yes
options, that allow skipping confirmation prompts.Added OS-X as a test environment to the Travis CI setup.
In the CLI, added a
-p
/--password
option for specifying the HMC password (issue #225).Added logging support to the zhmc CLI (issue #113).
Added ‘load-parameter’ option to ‘zhmc lpar load’ (issue #226).
Version 0.11.0
Released: 2017-03-16
Incompatible changes:
Changed the return value of all methods on resource classes that invoke asynchronous operations (i.e. all methods that have a wait_for_completion parameter), as follows:
For wait_for_completion=True, the JSON object in the ‘job-results’ field is now returned, or None if not present (i.e. no result data). Previously, the complete response was returned as a JSON object.
For wait_for_completion=False, a new Job object is now returned that allows checking and waiting for completion directly on the Job object. Previously, the whole response of the ‘Query Job Status’ operation was returned as a JSON object, and the job completion was checked on the Session object, and one could not wait for completion.
Changed the default value of the wait_for_completion parameter of the Session.post() method from True to False, in order to avoid superfluos timestats entries. This method is not normally used by users of the zhmcclient package.
Removed the version strings from the
args[]
property of thezhmcclient.VersionError
exception class. They had been available asargs[1]
andargs[2]
.args[0]
continues to be the error message, and themin_api_version
andapi_version
properties continue to provide the version strings.Changed the names of the Python loggers as follows:
Logger ‘zhmcclient.api’ logs API calls made by the user of the package, at log level DEBUG. Internal calls to API functions are no longer logged.
Logger ‘zhmcclient.hmc’ logs HMC operations. Their log level has been changed from INFO to DEBUG.
Removed the log calls for the HMC request ID.
Bug fixes:
Added a minimum version requirement >=4.0.0 for the dependency on the “decorate” Python package (issue #199).
Increased minimum version of “click-spinner” package to 0.1.7, in order to pick up the fix for zhmcclient issue #116.
Fixed CLI help text for multiple commands, where the text was incorrectly flowed into a paragraph.
Enhancements:
Added support for retry/timeout configuration of HTTP sessions, via a new
RetryTimeoutConfig
class that can be specified for theSession
object. The retry/timeout configuration can specify:HTTP connect timeout and number of retries.
HTTP read timeout (of HTTP responses), and number of retries.
Maximum number of HTTP redirects.
Added new exceptions
zhmcclient.ConnectTimeout
(for HTTP connect timeout),zhmcclient.ResponseReadTimeout
(for HTTP response read timeout), andzhmcclient.RequestRetriesExceeded
(for HTTP request retry exceeded). They are all derived fromzhmcclient.ConnectionError
.Fixed a discrepancy between documentation and actual behavior of the return value of all methods on resource classes that invoke asynchronous operations (i.e. all methods that have a wait_for_completion parameter). See also the corresponding incompatible change (issue #178).
In the CLI, added a ‘help’ command that displays help for interactive mode, and a one-line hint that explains how to get help and how to exit interactive mode (issue #197).
In the CLI, added support for command history. The history is stored in the file ~/.zhmc_history.
In the CLI, changed the prompt of the interactive mode to
zhmc>
.Added support for tolerating HTML content in the response, instead of JSON. An HTML formatted error message may be in the response for some 4xx and 5xx HTTP status codes (e.g. when the WS API is disabled). Such responses are raised as
HTTPError
exceptions with an artificial reason code of 999.Fixed an incorrect use of the
zhmcclient.AuthError
exception and unnecessary checking of HMC behavior, i.e. when the HMC fails with “API session token expired” for an operation that does not require logon. This error should never be returned for operations that do not require logon. If it would be returned, it is now handled in the same way as when the operation does require logon, i.e. by a re-logon.Added support for deferred status polling to the Lpar.activate/deactivate/load() methods. The HMC operations issued by these methods exhibit “deferred status” behavior, which means that it takes a few seconds after successful completion of the asynchronous job that executes the operation, until the new status can be observed in the ‘status’ property of the LPAR resource. These methods will poll the LPAR status until the desired status value is reached. A status timeout can be specified via a new status_timeout parameter to these methods, which defaults to 60 seconds. If the timeout expires, a new StatusTimeout exception is raised (issue #191).
Added operation timeout support to Session.post() and to all resource methods with a wait_for_completion parameter (i.e. the asynchronous methods). The operation timeout on the asynchronous methods can be specified via a new operation_timeout parameter, which defaults to 3600 seconds. If the timeout expires, a new OperationTimeout exception is raised (issue #6).
Added a new module that defines public constants, and that defines default timeout and retry values.
Experimental: In the CLI, added more supported table formats (plain, simple, psql, rst, mediawiki, html, LaTeX).
Improved the content of the log messages for logged API calls and HMC operations to now contain the function call arguments and return values (for API calls) and the HTTP request and response details (for HMC operations). For HMC operations and API calls that contain the HMC password, the password is hidden in the log message by replacing it with a few ‘*’ characters.
Version 0.10.0
Released: 2017-02-02
Incompatible changes:
The support for server-side filtering caused an incompatibility for the find() and findall() methods: For String typed resource properties, the provided filter string is now interpreted as a regular expression that is matched against the actual property value, whereby previously it was matched by exact string comparison.
The parameter signatures of the __init__() methods of BaseResource and BaseManager have changed incompatibly. These methods have always been considered internal to the package. They are now explicitly stated to be internal and their parameters are no longer documented. If users have made themselves dependent on these parameters (e.g. by writing a mock layer), they will need to adjust to the new parameter signature. See the code for details.
Bug fixes:
Fixed a bug where the CLI code tries to access ‘cpc’ from the ‘partition’ directly without going via the manager property. This caused an AttributeError (issue #161).
Fixed unrecognized field (‘adapter-port’) during ‘HBA create’ (issue #163).
Enhancements:
Added filter arguments to the list() method, and added support for processing as many filter arguments as supported on the server side via filter query parameters in the URI of the HMC List operation. The remaining filter arguments are processed on the client side in the list() method.
Changed the keyword arguments of the find() and findall() methods to be interpreted as filter arguments that are passed to the list() method.
Documented the authorization requirements for each method, and in total in a new section “Setting up the HMC”.
Added a method open_os_message_channel() on Partition and Lpar objects, that returns a notification token for receiving operating system messages as HMC notifications.
Experimental: Added a class NotificationReceiver that supports receiving and iterating through HMC notificationsi for a notification token, e.g. those produced by open_os_message_channel().
Version 0.9.0
Released: 2017-01-11
Bug fixes:
Fixed a bug where accessing the ‘name’ property via the properties attribute caused KeyError to be raised (issue #137). Note that there is now a recommendation to use get_property() or the name or uri attributes for accessing specific properties. The properties attribute should only be used for iterating over the currently present resource properties, but not for expecting particular properties.
Fixing regression in findall(name=..) (issue #141).
Enhancements:
Changed links to HMC API books in Bibliography to no longer require IBM ID (issue #131).
Added example shell script showing how to use the command line interface.
Improved the examples with better print messages, exception handling, access of resource properties, and refreshing of resources.
Added support for load-parameter field in lpar.load().
Version 0.8.0
Released: 2016-12-27
Enhancements:
Added support in CLI for remaining cmds; client improvements.
Added a tool ‘tools/cpcdata’ for gathering information about all CPCs managed by a set of HMCs. The data can optionally be appended to a CSV spreadsheet, for regular monitoring.
Version 0.7.0
Released: 2016-12-08
Bug fixes:
IOError during click-spinner 0.1.4 install (issue #120)
Enhancements:
Documentation for zhmc CLI
Version 0.6.0
Released: 2016-12-07
Bug fixes:
Fixed typo in help message of cpcinfo.
Fixed KeyError: ‘status’ when running example5.py (issue #99).
Fixed documentation of field Partition.hbas (issue #101).
Fixed new Flake8 issue E305.
Enhancements:
Started raising a ParseError exception when the JSON payload in a HTTP response cannot be parsed, and improved the definition of the ParseError exception by adding line and column information.
Improved the AuthError and ConnectionError exceptions by adding a details property that provides access to the underlying exception describing details.
For asynchronous operations that are invoked with wait_for_completion, added an entry in the time statistics for the overall operation from the start to completion of the asynchronous operation. That entry is for a URI that is the target URI, appended with “+completion”.
Added time statistics entry for overall asynchronous operations.
Improved VersionError exception class and removed number-of-args tests.
Added the option to create a session object with a given session id.
Added base implementation of a command line interface (zhmc) for the zhmcclient.
Version 0.5.0
Released: 2016-10-04
Incompatible changes:
In
VirtualSwitch.get_connected_vnics()
, renamed the method toget_connected_nics()
and changed its return value to returnNic
objects instead of their URIs.
Bug fixes:
Fixed that in Partition.dump_partition(), wait_for_completion was always passed on as True, ignoring the corresponding input argument.
Enhancements:
Added a script named
tools/cpcinfo
that displays information about CPCs. Invoke with-h
for help.Added a
prop()
method for resources that allows specifying a default value in case the property does not exist.Added
get_wwpns()
which performs HMC operation ‘Export WWPN List’.Added
reassign_port()
which performs HMC operation ‘Reassign Storage Adapter Port’.Clarifications in the Resource model section.
Optimized
dpm_enabled
property to use ‘List Partitions’ and ‘List Logical Partitions’ operations, in order to avoid the ‘List CPC Properties’ operation.Improved tutorials.
Version 0.4.0
Released: 2016-09-13
This is the base version for this change log.