Skip to content

Latest commit

 

History

History
538 lines (371 loc) · 17.6 KB

appendix.rst

File metadata and controls

538 lines (371 loc) · 17.6 KB
Raw

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

zhmcclient._manager

zhmcclient.BaseManager

zhmcclient._resource

zhmcclient.BaseResource

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 <py2:unicode> in Python 2, and py3:str in Python 3)

byte string

a byte string type (py2:str in Python 2, and py3:bytes in Python 3). Unless otherwise indicated, byte strings in this package are always UTF-8 encoded.

number

one of the number types py:int, py2:long (Python 2 only), or py:float.

integer

one of the integer types py:int or py2:long (Python 2 only).

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 py:dict object that is a Python representation of a valid JSON object. See py:py-to-json-table for details.

header dict

a py:dict object that specifies HTTP header fields, as follows:

  • key (string): Name of the header field, in any lexical case. Dictionary key lookup is case sensitive, however.
  • value (string): Value of the header field.
callable

a type for callable objects (e.g. a function, calling a class returns a new instance, instances are callable if they have a ~py:object.__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:

  • api_major_version (integer): The numeric major version of the HMC API.
  • api_minor_version (integer): The numeric minor version of the HMC API.

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

Capacity Record

TBD - Not yet supported.

CPC

Central Processor Complex, a physical IBM Z or LinuxONE computer.

For details, see section CPCs.

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 <storage volume>. 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 Group>.

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 <fulfillment>, 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 <Storage Volume>.

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 <NIC> 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:

  • Reset Activation Profile
  • Image Activation Profile
  • Load Activation Profile
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

ITU-T X.509, Information technology - Open Systems Interconnection - The Directory: Public-key and attribute certificate frameworks

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

IETF RFC6874, Representing IPv6 Zone Identifiers in Address Literals and Uniform Resource Identifiers, February 2013

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

Hardware Management Console Security

Related projects

zhmccli project

zhmccli project at GitHub

zhmccli package

zhmccli package on Pypi