10. Appendix¶
This section contains information that is referenced from other sections, and that does not really need to be read in sequence.
10.1. Troubleshooting¶
This section describes a few issues and how to address them.
10.1.1. 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.
10.1.2. 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.
10.2. 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.
- 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.
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.
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.
Authorization requirements:
Object-access permission to this resource.
- Parameters
- Returns
The value of the resource property.
- Raises
10.3. 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.
10.4. 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:
10.5. 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.
10.5.1. 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.
10.5.2. Resources scoped to CPCs in any mode¶
10.5.3. 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.
10.5.4. 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.
10.6. 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¶