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. No connection to the HMC

If you get errors that indicate there is no connection at all to the HMC, for example one of those errors:

Error: ConnectionError: HTTPSConnectionPool(host='10.11.12.13', port=6794): Max retries exceeded with url: /api/....
(Caused by ProxyError('Cannot connect to proxy.', OSError('Tunnel connection failed: 403 Forbidden',)))

Error: ConnectTimeout: HTTPSConnectionPool(host='10.11.12.13', port=6794): Max retries exceeded with url: /api/....
(Caused by ConnectTimeoutError(<urllib3.connection.HTTPSConnection object at 0x10a8c3910>, 'Connection to 10.11.12.13 timed out. (connect timeout=30)'))

then check all of the following:

  • Does the HMC have its Web Services API enabled?

    Refer to the respective item in Setting up the HMC for how to do that.

    If that is not enabled, the ports used by the Web Services API will be inactive on the HMC.

  • Do you have direct network connectivity to the HMC?

    You can test this with the following curl command:

    $ curl -k https://10.11.12.13:6794/api/version
{"api-major-version":4, .....

    If the HMC is reachable, this command displays JSON output with information about the HMC. Otherwise, it displays an error message. You can use the -v option of curl to get more details.

    Using ping to verify connectivity is also a possibility, but there are network environments in which ICMP traffic is dropped, and there are also network environments where ping works but some tunnelling or proxy is set up that requires special measures to get IP traffic through. So in order to draw conclusions from a ping result, you need to know how the network environment is set up between the system where you use the zhmcclient and the targeted HMC.

    Having ping work is at least a good indication. If ping works but the curl command above does not, then one possible reason is that the Web Services API is not enabled on the HMC.

  • Do you have a proxy setup to your HMC?

    In that case, you need to setup the proxy configuration such that you bypass the proxy. You need direct IP network connectivity between the system where you use the zhmcclient and the targeted HMC.

  • Do you have a firewall to your HMC?

    In case of a boundary firewall, you may need to log on to the boundary firewall.

    Also, the firewall needs to permit the ports used by the HMC API. For details, see Setting up firewalls or proxies.

  • Can you get to the HMC GUI via your web browser?

    If you can access the HMC GUI via your web browser but not the HMC API via the curl command shown above, then possible reasons are:

    • The HMC does not have its Web Services API enabled (see above).

    • There is a firewall to the HMC but it does not permit the ports used by the HMC API (see above).

10.1.2. 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.3. 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.1.4. ImportError urllib3 v2.0 only supports OpenSSL 1.1.1+ (macOS)

The ‘urllib3’ Python package version 2.0 has removed support for LibreSSL and wolfSSL and requires OpenSSL 1.1.1 or higher.

The ‘zhmcclient’ package uses the ‘requests’ package which uses ‘urllib3’, and neither ‘zhmcclient’ nor ‘requests’ pins ‘urllib3’ to stay below version 2.0. (if they did, that would prevent users from installing security fixes for urllib3).

Therefore, if you upgrade your Python packages, and you are using a Python that does not provide OpenSSL 1.1.1 or higher, you will see the following exception raised by urllib3:

ImportError: urllib3 v2.0 only supports OpenSSL 1.1.1+, currently the ‘ssl’ module is compiled with LibreSSL 2.8.3.
See: https://github.com/urllib3/urllib3/issues/2168

This can happen for example on macOS if you are using the system Python of macOS as the basis for a Python virtual environment and then install zhmcclient into that virtual environment, which typically installs the latest available versions of dependent packages, and thus may install urllib3 with a version 2.0 or later.

The ImportError exception message shows the name and version of the underlying SSL library the Python ‘ssl’ module is using. On most Python systems, that is a statically linked SSL library, so just installing OpenSSL 1.1.1 or higher does not address the issue.

You can verify for yourself which SSL library and version your Python uses:

(venv) $ python -c "import ssl; print(ssl.OPENSSL_VERSION)"
OpenSSL 1.1.1t  7 Feb 2023

$ /usr/bin/python3 -c "import ssl; print(ssl.OPENSSL_VERSION)"
LibreSSL 2.8.3

Note that Python since version 3.10 requires OpenSSL version 1.1.1 or higher (see PEP-644).

At least up to macOS Ventura, Apple compiles the system Python with LibreSSL. As long as that does not change, you cannot use the system Python of macOS with urllib3>=2.0; also not as a basis for Python virtual environments.

There are basically two options on how this issue can be addressed:

  • Use a Python version that uses OpenSSL 1.1.1 or higher. That is the case for the CPython reference implementation version 3.7 or higher. CPython can either be downloaded from https://www.python.org/downloads/macos/ or installed using a third party package installer for macOS, such as Homebrew.

  • Pin the urllib3 package to stay below version 2.0 when on Python 3.7 or higher, by specifying in your package dependencies, e.g. in your requirements.txt file:

    urllib3>=1.26.5,<2.0; python_version >= '3.7'

    The minimum version of urllib3 should be at least what the minimum-constraints.txt file of the zhmcclient project specifies as a minimum, for the zhmcclient version you are using.

    Note that pinning a dependent package prevents you from installing security fixes, which is important for a network related package such as urllib3, so this option should not be the preferred one.

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, case_insensitive_names=False, supports_properties=False)[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.

__repr__()[source]

Return a string with the state of this manager object, for debug purposes.

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 the RetryTimeoutConfig class.

property resource_class

The Python class of the parent resource of this manager.

property class_name

The resource class name

property name_prop

The name of the resource property indicating the resource name

property session

Session: Session with the HMC.

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.

property uri

The canonical URI path of the manager. Will not be None.

This URI uniquely identifies the list of HMC resources in scope of the manager, consistent with how the canonical URI path of a resource identifies the HMC resource.

The format of this URI is undocumented.

This URI is used in the implementation of auto-updated manager objects, it does not have any meaning on the HMC, and there should be no need for users to use it.

Type:

string

property case_insensitive_names

bool: Indicates whether the names of the resources are treated case insensitively.

property supports_properties

bool: Indicates whether the “Get Properties” operation for this type of resource supports the ‘properties’ query parameter in the latest released version of the HMC.

auto_update_enabled()[source]

Return whether Auto-updating is currently enabled for the manager object.

Returns:

Indicates whether auto-update is enabled.

Return type:

bool

auto_update_needs_pull()[source]

Return whether there is a need to pull the resources from the HMC, in the list() method.

This method is called in the list() method. It should not be called by the user.

enable_auto_update()[source]

Enable Auto-updating for this manager object, if currently disabled.

When enabling auto-update, the session to which this manager belongs is subscribed for auto-updating if needed (see subscribe_auto_update()), the manager object is registered with the session’s auto updater via register_object(), and all resources of this manager object are retrieved using list() in order to have the most current list of resources as a basis for the future auto-updating.

Raises:
disable_auto_update()[source]

Disable Auto-updating for this manager object, if currently enabled.

When disabling auto-updating, the manager object is unregistered from the session’s auto updater via unregister_object(), and the session is unsubscribed from auto-updating if the auto updater has no more objects registered.

auto_update_trigger_pull()[source]

Trigger the need to pull the resources from the HMC, in the list() method.

This method is called when an inventory change notification indicates that a new object on the HMC has been created. It should not be called by the user.

add_resources_local(resource_obj_list)[source]

Add a resource object to the local auto-updated list of resources.

This method is called in list() to put resources pulled from the HMC into the list of resources. It should not be called by the user.

remove_resource_local(resource_uri)[source]

Remove the resource object for a resource URI from the local auto-updated list of resources.

If the resource URI is not in that list, do nothing.

This method is called when an inventory change notification indicates that an object on the HMC has been deleted. It should not be called by the user.

list_resources_local()[source]

List the resource objects from the local auto-updated list of resources.

This method is called by the list() methods of resource manager classes. It should not be called by the user.

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 or element-uri

  • object-id or element-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 listing of resources is handled in an optimized way, as described in list().

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 listing of resources is handled in an optimized way, as described in list().

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.

If the resource name is specified in the filter arguments, it is matched with string comparison (i.e. not as a regular expression). The string comparison is case sensitive or case insensitive, dependent on the resource type.

Any other filter arguments are ignored if the resource name is specified, because the name is unique within the scope of this resource manager.

Returns:

Resource object in scope of this manager object that matches the filter arguments. This resource object has a minimal set of properties.

Raises:
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 listing of resources is handled in an optimized way:

  • If this manager is enabled for Auto-updating, a locally maintained resource list is used (which is automatically updated via inventory notifications from the HMC) and the provided filter arguments are applied.

  • Otherwise, for resources that have a List operation, the List operation is performed with the subset of the provided filter arguments that can be handled on the HMC side (this varies by resource type) and the remaining filter arguments are applied on the client side on the list result. For resources that are element objects without a List operation, the corresponding array property of the parent object is used to list the resources, and the provided filter arguments are applied.

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:

  • full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only a minimal set as returned by the list operation.

  • filter_args (dict) – Filter arguments. None 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 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 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() and findall() 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. The name is matched with string comparison (i.e. not as a regular expression). The string comparison is case sensitive or case insensitive, dependent on the resource type. Must not be None.

Returns:

Resource object in scope of this manager object that has the specified name. 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. The name is matched with string comparison (i.e. not as a regular expression). The string comparison is case sensitive or case insensitive, dependent on the resource type. 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 DeprecationWarning to be issued. Use invalidate_cache() instead.

dump()[source]

Dump the resources of this resource manager as a resource definition.

This is the default implementation for the case where the resource manager has no internal state that needs to be saved. If the resource manager does have internal state, this method needs to be overridden in the resource manager subclass.

The returned resource definition of this implementation has the following format:

[
    {...},  # resource definition
    ...
]
Returns:

Resource definitions of the resources of this resource manager.

Return type:

list

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() or list(). 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 Python dict 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() or prop() 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-updating 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.

If the resource object on the HMC no longer exists, the properties show the values that were last updated from the HMC when the object still existed.

Type:

immutable_views.DictView

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.

Raises:
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).

property ceased_existence

Indicates that the corresponding object on the HMC no longer exists, if auto-update is enabled for the resource. Always False, if auto-update is not enabled for the resource.

Type:

bool

pull_full_properties()[source]

Retrieve the full set of resource properties from the HMC and cache them in this Python object.

If the resource no longer exists on the HMC, CeasedExistence will be raised.

This method serializes with other methods that access or change resource properties on the same Python object.

Authorization requirements:

  • Object-access permission to this resource.

Raises:
pull_properties(properties)[source]

Retrieve the specified set of resource properties from the HMC and cache them in this Python object.

If no properties are specified, the method does nothing.

The values of other properties that may already be cached in this Python object remain unchanged.

If the HMC does not support property filtering for this type of resource, or if the resource on the HMC does not have one or more of the specified properties, the full set of properties is retrieved from the HMC and cached in this Python object.

If the resource no longer exists on the HMC, CeasedExistence will be raised.

This method serializes with other methods that access or change resource properties on the same Python object.

Authorization requirements:

  • Object-access permission to this resource.

Parameters:

properties (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.

Raises:
get_property(name)[source]

Return the value of a resource property.

If the resource property is not cached in this Python object, the full set of resource properties is retrieved from the HMC and cached in this Python object.

If the resource no longer exists on the HMC, CeasedExistence will be raised.

If the resource on the HMC does not have the property, KeyError will be raised.

This method serializes with other methods that access or change resource properties on the same Python object.

Authorization requirements:

  • Object-access permission to this resource.

Parameters:

name (string) – Name of the resource property, using the names defined in the respective ‘Data model’ sections in the HMC API book.

Returns:

The value of the resource property.

Raises:
prop(name, default=None)[source]

Return the value of a resource property, applying a default if the resource does not have a property with that name.

If the resource property is cached in this Python object, its value is used. Otherwise, the full set of resource properties is retrieved from the HMC and cached in this Python object.

If the resource no longer exists on the HMC, CeasedExistence is raised.

This method serializes with other methods that access or change resource properties on the same Python object.

Authorization requirements:

  • Object-access permission to this resource.

Parameters:

  • name (string) – Name of the resource property, using the names defined in the respective ‘Data model’ sections in the HMC API book.

  • default – Default value to be used, if the resource does not have a property with the specified name.

Returns:

The value of the resource property.

Raises:
get_properties_pulled(names)[source]

Return a set of resource properties with the values they currently have on the HMC.

If auto-update is enabled for the resource, the property value is returned from the (automatically updated) local cache. Otherwise, a “Get Properties” operation is performed to get the current values. If supported by the type of resource, the operation uses the ‘properties’ query parameter to restrict the response to the desired properties.

If the resource on the HMC does not have a property that was specified, its value will default to None.

If the resource no longer exists on the HMC, CeasedExistence is raised.

This method serializes with other methods that access or change resource properties on the same Python object.

Authorization requirements:

  • Object-access permission to this resource.

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.

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 cached in this Python object, without retrieving them from the HMC.

This method serializes with other methods that access or change resource 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 cached in this Python object. If a single value, it is used for all properties that are not cached. 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 to 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 resource properties on the same Python object.

Parameters:

properties (dict) –

Dictionary of new property values, with:

  • Key: Name of the property, using the names defined in the respective ‘Data model’ sections in the HMC API book.

  • Value: New value for the property.

cease_existence_local()[source]

Update this Python object to indicate that the corresponding HMC object no longer exists.

This method serializes with other methods that access or change resource 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 resource 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 resource 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-updating is currently enabled for the resource object.

Returns:

Indicates whether auto-update is enabled.

Return type:

bool

enable_auto_update()[source]

Enable Auto-updating 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 auto updater via register_object(), and all properties of this resource object are retrieved from the HMC using pull_full_properties() in order to have the most current values as a basis for the future auto-updating.

Raises:
disable_auto_update()[source]

Disable Auto-updating for this resource object, if currently enabled.

When disabling auto-updating, the resource object is unregistered from the session’s auto updater via unregister_object(), and the session is unsubscribed from auto-updating if the auto updater has no more objects registered.

dump()[source]

Dump this resource with its properties and child resources (recursively) as a resource definition.

This is the default implementation for the case where the resource has no child resources. If the resource does have child resources, this method needs to be overridden in the resource subclass.

The returned resource definition of this implementation has the following format:

{
    "properties": {...},
}
Returns:

Resource definition of this resource.

Return type:

dict

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, and str in Python 3)

byte string

a byte string type (str in Python 2, and bytes 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), or float.

integer

one of the integer types int or 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 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:

  • 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 __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.

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

Certificate

Represents X509 certificates.

Console

The HMC itself.

Group

A user-defined group of resources.

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.

MFA Server Definition

The information in an HMC about an MFA server that may be used for HMC user authorization purposes.

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

Capacity Record

TBD - Not yet supported.

CPC

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

For details, see section CPCs.

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.

A resource that interconnects two or more Partitions, using one of multiple interconnect technologies such as SMC-D, Hipersockets, or CTC.

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

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) (no longer available for download)

HMC API 2.12.0

IBM SC27-2617, System z Hardware Management Console Web Services API (Version 2.12.0) (no longer available for download)

HMC API 2.12.1

IBM SC27-2626, System z Hardware Management Console Web Services API (Version 2.12.1) (no longer available for download)

HMC API 2.13.0

IBM SC27-2627-00a, z Systems Hardware Management Console Web Services API (Version 2.13.0)

HMC API 2.13.1

IBM SC27-2634-03a, z Systems Hardware Management Console Web Services API (Version 2.13.1)

HMC API 2.14.0

IBM SC27-2636-04a, IBM Z Hardware Management Console Web Services API (Version 2.14.0)

HMC API 2.14.1

IBM SC27-2637-01a, IBM Z Hardware Management Console Web Services API (Version 2.14.1)

HMC API 2.15.0

IBM SC27-2638-04c, IBM Z Hardware Management Console Web Services API (Version 2.15.0) (covers both GA1 and GA2)

HMC API 2.16.0

IBM SC27-2642-02, IBM Z Hardware Management Console Web Services API (Version 2.16.0) (covers both GA1 and GA2)

HMC Security

IBM SC28-6987-01, Hardware Management Console Security