5. 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	`bool`
Byte, Integer, Long, Short	integer
Float	`float`
String, String Enum	unicode string
timestamp	integer
Array	`list`
Object	`dict`

5.1. 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:

cpcs

Attributes:

`client`	`Client`: The client defining the scope for this manager.
`console`	`Console`: The Console representing the HMC this CPC is managed by.
`case_insensitive_names`	`bool`: Indicates whether the names of the resources are treated case insensitively.
`class_name`	The resource class name
`name_prop`	The name of the resource property indicating the resource 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.
`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.
`uri`	The canonical URI path of the manager.

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.
`add_resources_local`(resource_obj_list)	Add a resource object to the local auto-updated list of resources.
`auto_update_enabled`()	Return whether Auto-updating is currently enabled for the manager object.
`auto_update_needs_pull`()	Return whether there is a need to pull the resources from the HMC, in the list() method.
`auto_update_trigger_pull`()	Trigger the need to pull the resources from the HMC, in the list() method.
`disable_auto_update`()	Disable Auto-updating for this manager object, if currently enabled.
`dump`()	Dump the resources of this resource manager as a resource definition.
`enable_auto_update`()	Enable Auto-updating for this manager object, if currently disabled.
`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. for a CPC, a `Cpc` object is returned).
`find_by_name`(name)	Find a resource by name and return its Python resource object (e.g. for a CPC, a `Cpc` object is returned).
`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. for CPCs, a list of `Cpc` objects is returned).
`flush`()	Invalidate the Name-URI cache of this manager.
`invalidate_cache`()	Invalidate the Name-URI cache of this manager.
`list_resources_local`()	List the resource objects from the local auto-updated list of resources.
`remove_resource_local`(resource_uri)	Remove the resource object for a resource URI from the local auto-updated list of resources.
`resource_object`(uri_or_oid[, props])	Return a minimalistic Python resource object for this resource class, that is scoped to this manager.

property client: Client: The client defining the scope for 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() or prop() 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.

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, if the filter arguments specify the resource name as a single filter argument with a straight match string (i.e. without regular expressions), an optimized lookup is performed based on a locally maintained name-URI cache.
Otherwise, the HMC List operation is performed with the subset of the provided filter arguments that can be handled on the HMC side and the remaining filter arguments are applied on the client side on the list result.

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:

`lpars`	Access to the LPARs in this CPC.
`partitions`	Access to the Partitions in this CPC.
`adapters`	Access to the Adapters in this CPC.
`virtual_switches`	Access to the Virtual Switches in this CPC.
`capacity_groups`	Access to the Capacity Groups in this CPC.
`vswitches`	Access to the Virtual Switches in this CPC.
`reset_activation_profiles`	Access to the Reset Activation Profiles in this CPC.
`image_activation_profiles`	Access to the Image Activation Profiles in this CPC.
`load_activation_profiles`	Access to the Load Activation Profiles in this CPC.
`dpm_enabled`	Indicates whether this CPC is currently in DPM mode (Dynamic Partition Manager mode).
`maximum_active_partitions`	The maximum number of partitions of this CPC.
`ceased_existence`	Indicates that the corresponding object on the HMC no longer exists, if auto-update is enabled for the 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:

`dump`()	Dump this Cpc resource with its properties and child resources (recursively) as a resource definition.
`feature_enabled`(feature_name)	Indicates whether the specified feature is enabled for this CPC.
`feature_info`()	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 DPM-mode CPC, using the HMC operation "Stop CPC".
`activate`(activation_profile_name[, force, ...])	Activate this classic-mode CPC, using the HMC operation "Activate CPC".
`deactivate`([force, wait_for_completion, ...])	Deactivate this CPC, using the HMC operation "Deactivate 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.
`get_energy_management_properties`()	Return the energy management properties of the CPC.
`list_associated_storage_groups`([...])	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_dpm_configuration`([...])	Export a DPM configuration from this CPC and return it.
`list_api_features`([name])	Returns information about the Web Services API features (introduced with Web Services version 4.10) available on the CPC, see Feature enablement.
`single_step_install`([bundle_level, ...])	Upgrades the firmware on the Support Element (SE) of this CPC.
`install_and_activate`([bundle_level, ...])	Installs and activates firmware on the Support Element (SE) of this CPC.
`delete_retrieved_internal_code`([ec_levels, ...])	Deletes retrieved updates that have not been installed on the Support Element (SE) of this CPC.
`swap_current_time_server`(stp_id)	Makes this CPC the current time server of an STP-only Coordinated Timing Network (CTN).
`set_stp_config`(stp_id, new_stp_id, force, ...)	Sets the configuration of the STP-only Coordinated Timing Network (CTN) whose current time server is this CPC.
`change_stp_id`(stp_id)	Changes the STP identifier of the STP-only Coordinated Timing Network (CTN) whose current time server is this CPC.
`join_ctn`(stp_id)	Causes this CPC to join an STP-only Coordinated Timing Network (CTN).
`leave_ctn`()	Causes this CPC to leave its current STP-only Coordinated Timing Network (CTN).
`__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-updating is currently enabled for the resource object.
`cease_existence_local`()	Update this Python object to indicate that the corresponding HMC object no longer exists.
`disable_auto_update`()	Disable Auto-updating for this resource object, if currently enabled.
`enable_auto_update`()	Enable Auto-updating 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 cached in this Python object, without retrieving them from the HMC.
`get_properties_pulled`(names)	Return a set of resource properties with the values they currently have on 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 the resource does not have a property with that name.
`pull_full_properties`()	Retrieve the full set of resource properties from the HMC and cache them in this Python object.
`pull_properties`(properties)	Retrieve the specified set of resource properties from the HMC and cache them in this Python object.
`update_properties_local`(properties)	Update the values of a set of resource properties on this Python object without propagating the updates to the HMC.

property lpars

Access to the LPARs in this CPC.

Type:: LparManager

property partitions

Access to the Partitions in this CPC.

Type:: PartitionManager

property adapters

Access to the Adapters in this CPC.

Type:: AdapterManager

property virtual_switches

Access to the Virtual Switches in this CPC.

Type:: VirtualSwitchManager

property capacity_groups

Access to the Capacity Groups in this CPC.

Type:: CapacityGroupManager

property vswitches

Access to the Virtual Switches in this CPC.

Deprecated: This attribute is deprecated and using it will cause a DeprecationWarning to be issued. Use virtual_switches instead.

Type:: VirtualSwitchManager

property reset_activation_profiles

Access to the Reset Activation Profiles in this CPC.

Type:: ActivationProfileManager

property image_activation_profiles

Access to the Image Activation Profiles in this CPC.

Type:: ActivationProfileManager

property load_activation_profiles

Access to the Load Activation Profiles in this CPC.

Type:: ActivationProfileManager

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:

bool

property maximum_active_partitions

The maximum number of partitions of this CPC.

For CPCs in DPM mode, the number indicates the maximum number of partitions. For CPCs in classic mode, the number indicates the maximum number of logical partitions (LPARs) that can be active at the same time.

The following table shows the maximum number of partitions by machine generation:

Machine generation	Maximum partitions
z196	60
z114	30
zEC12	60
zBC12	30
z13 / Emperor	85
z13s / Rockhopper	40
z14 / Emperor II	85
z14-ZR1 / Rockhopper II	40
z15-T01 / LinuxOne III (-LT1)	85
z15-T02 / LinuxOne III (-LT2)	40
z15-GT2	85
z16-A01	85

Raises:

HTTPError –
ParseError –
AuthError –
ConnectionError –
ValueError – Unknown machine type

Type:

Integer

dump()[source]

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

The returned resource definition has the following format:

{
    # Resource properties:
    "properties": {...},

    # Child resources for any CPC mode:
    "capacity_groups": [...],

    # Child resources for DPM mode:
    "partitions": [...],
    "adapters": [...],
    "virtual_switches": [...],

    # Child resources for classic mode:
    "lpars": [...],  # Faked Lpar children
    "reset_activation_profiles": [...],
    "image_activation_profiles": [...],
    "load_activation_profiles": [...],
}

Returns:: Resource definition of this resource.
Return type:: dict

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:

bool

Raises:

ValueError – Features are not supported on the HMC.
ValueError – The specified feature is not available for the CPC.
HTTPError –
ParseError –
AuthError –
ConnectionError –

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:

iterable

Raises:

ValueError – Features are not supported on the HMC.
HTTPError –
ParseError –
AuthError –
ConnectionError –

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.

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 ‘CPC’ in the HMC API book.

Raises:

start(wait_for_completion=True, operation_timeout=None)[source]

Start this CPC, using the HMC operation “Start CPC”.

This operation performs an orderly start of the CPC, including:

Turning CPC power on.
Performing a power-on reset, this includes allocating system resources to the CPC.
Starting partitions that are in the auto-start list of the CPC.

The CPC must be set for DPM operational mode (i.e. its ‘dpm-enabled’ property is True) and must currently be inactive.

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.

This job supports cancellation. Note that it may no longer be possible to cancel the job after some point. The job status and reason codes will indicate whether the job was canceled or ran to completion.

Return type:

None or Job

Raises:

HTTPError –
ParseError –
AuthError –
ConnectionError –
OperationTimeout – The timeout expired while waiting for completion of the operation.

stop(wait_for_completion=True, operation_timeout=None)[source]

Stop this DPM-mode CPC, using the HMC operation “Stop CPC”.

This operation performs an orderly shutdown of the CPC, including:

Stopping all partitions.
Ending hardware activity.
Clearing, releasing, and de-allocating hardware resources.
Turning off CPC power.

The CPC must be set for DPM operational mode (i.e. its ‘dpm-enabled’ property is True) and must currently be active.

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. This job does not support cancellation.

Return type:

None or Job

Raises:

HTTPError –
ParseError –
AuthError –
ConnectionError –
OperationTimeout – The timeout expired while waiting for completion of the operation.

activate(activation_profile_name, force=False, wait_for_completion=True, operation_timeout=None)[source]

Activate this classic-mode CPC, using the HMC operation “Activate CPC”.

This operation performs an orderly start of the CPC, including:

Turning CPC power on.
Performing a power-on reset, this includes allocating system resources to the CPC as defined by the reset activation profile.
Activating LPARs that are in the auto-start list defined by the reset activation profile.

If the CPC is already active in classic mode, only the operations are performed that are needed to get into the state defined by the specified reset activation profile.

The CPC must be set for classic operational mode (i.e. its ‘dpm-enabled’ property is False).

Authorization requirements:

Object-access permission to this CPC.
Task permission for the “Activate” task.

Parameters:

activation_profile_name (string) – Name of the reset activation profile used to activate the CPC.
force (bool) – Boolean controlling whether the operation is permitted if the CPC is in ‘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.
- 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. This job does not support cancellation.

Return type:

None or Job

Raises:

HTTPError –
ParseError –
AuthError –
ConnectionError –
OperationTimeout – The timeout expired while waiting for completion of the operation.

deactivate(force=False, wait_for_completion=True, operation_timeout=None)[source]

Deactivate this CPC, using the HMC operation “Deactivate CPC”.

This operation performs an orderly shutdown of the CPC, including:

Stopping all LPARs.
Ending hardware activity.
Clearing, releasing, and de-allocating hardware resources.
Turning off CPC power.

The CPC must be set for classic operational mode (i.e. its ‘dpm-enabled’ property is False).

Authorization requirements:

Object-access permission to this CPC.
Task permission for the “Deactivate” task.

Parameters:

force (bool) – Boolean controlling whether the operation is permitted if the CPC is in ‘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.
- 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. This job does not support cancellation.

Return type:

None or Job

Raises:

HTTPError –
ParseError –
AuthError –
ConnectionError –
OperationTimeout – The timeout expired while waiting for completion of the operation.

import_profiles(profile_area)[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.

Raises:

export_profiles(profile_area)[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.

Raises:

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:

HTTPError – See the HTTP status and reason codes of operation “Export WWPN List” in the HMC API book.
ParseError –
AuthError –
ConnectionError –

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 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 if crypto_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. This job does not support cancellation.

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.
ParseError –
AuthError –
ConnectionError –
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 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. This job does not support cancellation.

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.
ParseError –
AuthError –
ConnectionError –
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:

dict

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.
AuthError –
ConnectionError –

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
HTTPError –
ParseError –
AuthError –
ConnectionError –

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 its reason 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.
Object-access permission to Secure Boot Certificate objects (only applies when the request body contains one or more secure boot Certificate objects to be assigned to Partitions).
Task permission for the “Import Secure Boot Certificates” task (only applies when the request body contains one or more Certificate objects).
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:

list or None

Raises:

export_dpm_configuration(include_unused_adapters=False)[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, various storage and tape related resources, and certificate objects.

By default, only those adapters of the CPC are exported that are referenced by other DPM specific objects.

This method performs the “Get Inventory” HMC operation and extracts the relevant elements into the result.

This method requires the CPC to be in DPM mode.

Authorization requirements:

Object-access permission to this CPC.
Object-access permission to all Certificate objects associated to this CPC.

Parameters:

include_unused_adapters (bool) – Controls whether the full set of adapters should be returned, vs. only those that are referenced by other DPM objects that are part of the return data.

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.

Empty fields are omitted from the returned configuration. This allows using newer versions of zhmcclient that may have added support for a feature of a new generation of Z systems with older generations of Z systems that did not yet have the feature.

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:

dict

Raises:

HTTPError –
ParseError –
AuthError –
ConnectionError –
ConsistencyError –

list_api_features(name=None)[source]

Returns information about the Web Services API features (introduced with Web Services version 4.10) available on the CPC, see Feature enablement.

Parameters:: name – A regular expression used to limit returned objects to those that have a matching name field.

Authorization requirements:

None

Returns:: The list of API features that are available on this CPC. For API versions prior to 4.10, an empty list is returned.
Return type:: list of strings

single_step_install(bundle_level=None, accept_firmware=True, ftp_host=None, ftp_protocol=None, ftp_user=None, ftp_password=None, ftp_directory=None, wait_for_completion=True, operation_timeout=None)[source]

Upgrades the firmware on the Support Element (SE) of this CPC.

This is done by performing the “CPC Single Step Install” operation which performs the following steps:

A backup of the target CPC is performed to its SE hard drive.
If accept_firmware is True, the firmware currently installed on the SE of this CPC is accepted. Note that once firmware is accepted, it cannot be removed.
The new firmware identified by the bundle-level field is retrieved from the IBM support site or from an FTP server, and installed.
The newly installed firmware is activated, which includes rebooting the SE of this CPC.

If an error occurs when installing the upgrades for the different firmware components, any components that were successfully installed are rolled back.

If an error occurs after the firmware is accepted, the firmware remains accepted.

Note that it is not possible to downgrade the SE firmware with this operation.

Authorization requirements:

Object-access permission to this CPC.
Task permission to the “Single Step Internal Code Changes” task.

Parameters:

bundle_level (string) – Name of the bundle to be installed on the SE of this CPC (e.g. ‘S51’). If None, all locally available code changes, or in case of retrieving code changes from an FTP server, all code changes on the FTP server, will be installed.
accept_firmware (bool) – Accept the previous bundle level before installing the new level.
ftp_host (string) – The hostname for the FTP server from which the firmware will be retrieved, or None to retrieve it from the IBM support site.
ftp_protocol (string) – The protocol to connect to the FTP server, if the firmware will be retrieved from an FTP server, or None. Valid values are: “ftp”, “ftps”, “sftp”.
ftp_user (string) – The username for the FTP server login, if the firmware will be retrieved from an FTP server, or None.
ftp_password (string) – The password for the FTP server login, if the firmware will be retrieved from an FTP server, or None.
ftp_directory (string) – The path name of the directory on the FTP server with the firmware files, if the firmware will be retrieved from an FTP server, or None.
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.

This job supports cancellation. Note there are only a few interruption points in the firmware install process, so it may be some time before the job is canceled, and after some point, will continue on to completion. The job status and reason codes will indicate whether the job was canceled or ran to completion. If the job is successfully canceled, any steps that were successfully completed will not be rolled back.

Return type:

None or Job

Raises:

HTTPError –
ParseError –
AuthError –
ConnectionError –
OperationTimeout – The timeout expired while waiting for completion of the operation.

install_and_activate(bundle_level=None, ec_levels=None, install_disruptive=False, wait_for_completion=True, operation_timeout=None)[source]

Installs and activates firmware on the Support Element (SE) of this CPC.

Brief summary of firmware levels:

The firmware is segmented into different subsystems called “Engineering Change” (EC), or sometimes “EC stream”. An EC stream is identified by an EC number (e.g. “P30719”).

Each EC stream is at a particular code level called “Microcode Level” (MCL), or sometimes “MCL level”. An MCL level for an EC stream is identified by an MCL number (e.g. “001”). MCL numbers are unique only within their EC stream and are consecutive numbers that increase towards newer MCL levels. Updates within an EC stream are installed sequentially, so if an EC stream has a particular MCL level installed, that implies that all earlier MCL levels within that EC stream are also installed.

A particular set of MCL numbers for each EC stream is collected into a “bundle level” for the SE (e.g. “S81”) or HMC (e.g. “H20”).

The firmware level for this method can be specified in three ways:

By specifying bundle_level: The updates for the specified bundle level will be installed.
By specifying ec_levels: Specific MCL levels for the specified EC streams will be installed.
By not specifying bundle_level and `ec_levels: All locally available updates will be installed.

In all cases, the updates to be installed must already be available on the SE; they are not automatically downloaded from the IBM support site or from an FTP server.

This method is implemented by performing the “CPC Install and Activate” operation which performs the following steps:

The specified updates are installed.
If all updates are installed successfully, they are activated, which includes rebooting the SE of this CPC.

If an error occurs when installing the updates, any updates that were successfully installed are rolled back.

Note that this operation does not perform a backup, an accept of previously activated updates, or an accept of the newly installed updates.

Note that this operation does not require that previously activated updates are first accepted before invoking this operation.

Note that it is not possible to downgrade the SE firmware with this operation.

Authorization requirements:

Object-access permission to this CPC.
Task permission to the “Change Internal Code” task.

Parameters:

bundle_level (string) –
Name of the bundle to be installed on the SE of this CPC (e.g. ‘S51’).

This parameter is mutually exclusive with ec_levels. If both are not provided, all locally available updates will be installed.
ec_levels (list of tuple(ec,mcl)) –
Updates to be installed on the SE of this CPC, as a list of tuples (ec, mcl) where:
- ec (string): EC number of the EC stream (e.g. “P30719”)
- mcl (string): MCL number within the EC stream (e.g. “001”)
This parameter is mutually exclusive with bundle_level. If both are not provided, all locally available updates will be installed.
install_disruptive (bool) –
Install disruptive changes.
- If True, all firmware will be installed regardless of whether it is disruptive to CPC operations.
- If False and bundle_level or ec_levels is specified, the request will fail if the operation encounters a disruptive change.
- If False and neither bundle_level or ec_levels are specified, all concurrent changes will be installed, and the disruptive ones will be left uninstalled.
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 a string that is the ‘message’ field of the successfully completed job, or None if the successfully completed job has no message.

If wait_for_completion is False, returns a Job object representing the asynchronously executing job on the HMC. This job does not support cancellation. Once that job successfully completes, it may optionally have a ‘message’ field in its ‘job-results’ field.

In all cases, if a message is returned it may indicate that disruptive updates were not installed, or that updates are in pending state because some follow-up action is needed. In the latter case, the “View Internal Code Changes Summary” task on the HMC or SE GUI will provide a list of the additional actions that are required. It is not possible to query this information via the API.

Return type:

string or None or Job

Raises:

HTTPError –
ParseError –
AuthError –
ConnectionError –
OperationTimeout – The timeout expired while waiting for completion of the operation.

delete_retrieved_internal_code(ec_levels=None, wait_for_completion=True, operation_timeout=None)[source]

Deletes retrieved updates that have not been installed on the Support Element (SE) of this CPC.

This is done by performing the “CPC Delete Retrieved Internal Code” operation which performs the following steps:

The specified retrieved and uninstalled firmware updates are deleted from the SE of this CPC.

If an error occurs when deleting the updates, then only the updates that were unsuccessfully deleted will remain on the system; any updates that were deleted before reaching an error will remain deleted upon completion of the operation.

Note that it is not possible to downgrade the SE firmware with this operation.

Authorization requirements:

Object-access permission to this CPC.
Task permission to the “Change Internal Code” task.

Parameters:

ec_levels (list of tuple(ec,mcl)) –
The MCL levels of retrieved and uninstalled updates that will be deleted on the SE of this CPC, as a list of tuples (ec, mcl) where:
- ec (string): EC number of the EC stream (e.g. “P30719”)
- mcl (string): MCL number within the EC stream (e.g. “001”)
Within each specified EC stream, only the one update for the specified MCL level will be deleted.

If None, all retrieved and uninstalled updates are deleted on the SE of this CPC.
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. This job does not support cancellation.

Return type:

None or Job

Raises:

HTTPError –
ParseError –
AuthError –
ConnectionError –
OperationTimeout – The timeout expired while waiting for completion of the operation.

swap_current_time_server(stp_id)[source]

Makes this CPC the current time server of an STP-only Coordinated Timing Network (CTN).

This is done by performing the “Swap Current Time Server” operation.

The CTN must be STP-only; mixed CTNs will be rejected.

Authorization requirements:

Object-access permission to this CPC.
Task permission to the “Manage System Time” and “Modify Assigned Server Roles” tasks.

Parameters:

stp_id (string) – STP identifier of the CTN.

Raises:

set_stp_config(stp_id, new_stp_id, force, preferred_time_server, backup_time_server, arbiter, current_time_server)[source]

Sets the configuration of the STP-only Coordinated Timing Network (CTN) whose current time server is this CPC.

This is done by performing the “Set STP Configuration” operation.

The CTN must be STP-only; mixed CTNs will be rejected.

Authorization requirements:

Object-access permission to this CPC.
Task permission to the “Manage System Time” and “Modify Assigned Server Roles” tasks.

Parameters:

stp_id (string) – Current STP identifier of the CTN to be updated. This CPC must be the current time server of the CTN.
new_stp_id (string) – The new STP identifier for the CTN. If None, the STP identifier of the CTN is not changed.
force (bool) – Required. Indicates whether a disruptive operation is allowed (True) or rejected (False). Must not be None.
preferred_time_server (zhmcclient.STPNode) – Identifies the CPC to be the preferred time server of the CTN. Must not be None.
backup_time_server (zhmcclient.STPNode) – Identifies the CPC to be the backup time server of the CTN. If None, the CTN will have no backup time server.
arbiter (zhmcclient.STPNode) – Identifies the CPC to be the arbiter for the CTN. If None, the CTN will have no arbiter.
current_time_server (string) –
Identifies which time server takes on the role of the current time server. Must be one of:
- ”preferred” - the preferred time server is the current time server
- ”backup” - the backup time server is the current time server
Must not be None.

Raises:

change_stp_id(stp_id)[source]

Changes the STP identifier of the STP-only Coordinated Timing Network (CTN) whose current time server is this CPC.

This is done by performing the “Change STP-only Coordinated Timing Network” operation.

The CTN must be STP-only; mixed CTNs will be rejected.

Authorization requirements:

Object-access permission to this CPC.
Task permission to the “Manage System Time” and “Rename CTN” tasks.

Parameters:

stp_id (string) – STP identifier of the CTN to be updated. This CPC must be the current time server of the CTN.

Raises:

join_ctn(stp_id)[source]

Causes this CPC to join an STP-only Coordinated Timing Network (CTN).

This is done by performing the “Join STP-only Coordinated Timing Network” operation.

If the CPC is already a member of a different CTN but not in the role of the current time server, it is removed from that CTN.

If the CPC object has an ETR ID, the ETR ID is removed.

The CPC must not be the current time server of a different CTN.

The CTN must be STP-only; mixed CTNs will be rejected.

Authorization requirements:

Object-access permission to this CPC.
Task permission to the “Manage System Time” and “Add Systems to CTN” tasks.

Parameters:

stp_id (string) – STP identifier of the CTN to be joined.

Raises:

leave_ctn()[source]

Causes this CPC to leave its current STP-only Coordinated Timing Network (CTN).

This is done by performing the “Leave STP-only Coordinated Timing Network” operation.

The CTN must be STP-only; mixed CTNs will be rejected.

The CPC must not be the current time server of its current CTN.

Authorization requirements:

Object-access permission to this CPC.
Task permission to the “Manage System Time” and “Remove Systems from CTN” tasks.

Raises:

class zhmcclient.STPNode(object_uri, type, model, manuf, po_manuf, seq_num, node_name)[source]

Data structure defining a CPC that is referenced by an STP configuration.

That CPC does not need to be managed by the HMC.

This object is used in the following methods:

zhmcclient.Cpc.set_stp_config()

Parameters:

object_uri (string) – The object-uri of the CPC, if the CPC is managed by the HMC. Otherwise, None.
type (string) – Machine type of the CPC (6 chars left padded with zeros), or an empty string.
model (string) – Machine model of the CPC (3 chars), or an empty string.
manuf (string) – Manufacturer of the CPC (3 chars), or an empty string.
po_manuf (string) – Plant code of the manufacturer of the CPC (2 chars), or an empty string.
seq_num (string) – Sequence number of the CPC (12 chars), or an empty string.
node_name (string) – Name of the CPC (1-8 chars).

Methods:

json()

Returns this data structure as a JSON string suitable for being used as an argument in methods that use this data structure.

json()[source]: Returns this data structure as a JSON string suitable for being used as an argument in methods that use this data structure.

5.2. 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:

unmanaged_cpcs

Attributes:

`console`	Console defining the scope for this manager.
`case_insensitive_names`	`bool`: Indicates whether the names of the resources are treated case insensitively.
`class_name`	The resource class name
`name_prop`	The name of the resource property indicating the resource 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.
`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.
`uri`	The canonical URI path of the manager.

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.
`add_resources_local`(resource_obj_list)	Add a resource object to the local auto-updated list of resources.
`auto_update_enabled`()	Return whether Auto-updating is currently enabled for the manager object.
`auto_update_needs_pull`()	Return whether there is a need to pull the resources from the HMC, in the list() method.
`auto_update_trigger_pull`()	Trigger the need to pull the resources from the HMC, in the list() method.
`disable_auto_update`()	Disable Auto-updating for this manager object, if currently enabled.
`dump`()	Dump the resources of this resource manager as a resource definition.
`enable_auto_update`()	Enable Auto-updating for this manager object, if currently disabled.
`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. for a CPC, a `Cpc` object is returned).
`find_by_name`(name)	Find a resource by name and return its Python resource object (e.g. for a CPC, a `Cpc` object is returned).
`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. for CPCs, a list of `Cpc` objects is returned).
`flush`()	Invalidate the Name-URI cache of this manager.
`invalidate_cache`()	Invalidate the Name-URI cache of this manager.
`list_resources_local`()	List the resource objects from the local auto-updated list of resources.
`remove_resource_local`(resource_uri)	Remove the resource object for a resource URI from the local auto-updated list of resources.
`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 defining the scope for this manager.

Type:: Console

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

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, if the filter arguments specify the resource name as a single filter argument with a straight match string (i.e. without regular expressions), an optimized lookup is performed based on a locally maintained name-URI cache.
Otherwise, the HMC List operation is performed with the subset of the provided filter arguments that can be handled on the HMC side and the remaining filter arguments are applied on the client side on the list result.

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-updating is currently enabled for the resource object.
`cease_existence_local`()	Update this Python object to indicate that the corresponding HMC object no longer exists.
`disable_auto_update`()	Disable Auto-updating for this resource object, if currently enabled.
`dump`()	Dump this resource with its properties and child resources (recursively) as a resource definition.
`enable_auto_update`()	Enable Auto-updating 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 cached in this Python object, without retrieving them from the HMC.
`get_properties_pulled`(names)	Return a set of resource properties with the values they currently have on 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 the resource does not have a property with that name.
`pull_full_properties`()	Retrieve the full set of resource properties from the HMC and cache them in this Python object.
`pull_properties`(properties)	Retrieve the specified set of resource properties from the HMC and cache them in this Python object.
`update_properties_local`(properties)	Update the values of a set of resource properties on this Python object without propagating the updates to the HMC.

Attributes:

`ceased_existence`	Indicates that the corresponding object on the HMC no longer exists, if auto-update is enabled for the 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.

5.3. Groups

A Group is a user-defined group of resources that are managed by the HMC.

Groups can be used for example in User Role permissions.

Groups can be one of two kinds:

pattern-matching groups: Membership is implicit and the result of pattern matching on the resource name. This is supported only for members that are CPCs, Logical Partitions (i.e. classic mode), or other Groups.
explicit groups: Each member is added and removed explicitly, using the Group.add_member() and Group.remove_member() methods.

class zhmcclient.GroupManager(console)[source]

Manager providing access to the Groups exposed by the HMC this client is connected to.

Derived from BaseManager; see there for common methods and attributes.

Attributes:

`console`	Console defining the scope for this manager.
`case_insensitive_names`	`bool`: Indicates whether the names of the resources are treated case insensitively.
`class_name`	The resource class name
`name_prop`	The name of the resource property indicating the resource 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.
`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.
`uri`	The canonical URI path of the manager.

Methods:

`list`([full_properties, filter_args])	List the Groups managed by the HMC this client is connected to.
`create`(properties)	Create a Group in the HMC.
`__repr__`()	Return a string with the state of this manager object, for debug purposes.
`add_resources_local`(resource_obj_list)	Add a resource object to the local auto-updated list of resources.
`auto_update_enabled`()	Return whether Auto-updating is currently enabled for the manager object.
`auto_update_needs_pull`()	Return whether there is a need to pull the resources from the HMC, in the list() method.
`auto_update_trigger_pull`()	Trigger the need to pull the resources from the HMC, in the list() method.
`disable_auto_update`()	Disable Auto-updating for this manager object, if currently enabled.
`dump`()	Dump the resources of this resource manager as a resource definition.
`enable_auto_update`()	Enable Auto-updating for this manager object, if currently disabled.
`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. for a CPC, a `Cpc` object is returned).
`find_by_name`(name)	Find a resource by name and return its Python resource object (e.g. for a CPC, a `Cpc` object is returned).
`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. for CPCs, a list of `Cpc` objects is returned).
`flush`()	Invalidate the Name-URI cache of this manager.
`invalidate_cache`()	Invalidate the Name-URI cache of this manager.
`list_resources_local`()	List the resource objects from the local auto-updated list of resources.
`remove_resource_local`(resource_uri)	Remove the resource object for a resource URI from the local auto-updated list of resources.
`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 defining the scope for this manager.

Type:: Console

list(full_properties=False, filter_args=None)[source]

List the Groups managed by the HMC this client is connected to.

Authorization requirements:

Object-access permission to any Group 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 Group objects.

Raises:

create(properties)[source]

Create a Group in the HMC.

Authorization requirements:

Task permission to the “Grouping” task.

Parameters:

properties (dict) – Initial property values. Allowable properties are defined in section ‘Request body contents’ in section ‘Create Custom Group’ in the HMC API book.

Returns:

The resource object for the new 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:

Group

Raises:

class zhmcclient.Group(manager, uri, name=None, properties=None)[source]

Representation of a 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, GroupManager).

Note that Group objects do not have any writeable properties, so they do not have an update_properties() method.

Methods:

`dump`()	Dump this Group resource with its properties as a resource definition.
`delete`()	Delete this Group.
`add_member`(uri)	Add a resource as a new member to the Group.
`remove_member`(uri)	Remove a member resource from the Group.
`list_members`()	List Group members.
`__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-updating is currently enabled for the resource object.
`cease_existence_local`()	Update this Python object to indicate that the corresponding HMC object no longer exists.
`disable_auto_update`()	Disable Auto-updating for this resource object, if currently enabled.
`enable_auto_update`()	Enable Auto-updating 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 cached in this Python object, without retrieving them from the HMC.
`get_properties_pulled`(names)	Return a set of resource properties with the values they currently have on 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 the resource does not have a property with that name.
`pull_full_properties`()	Retrieve the full set of resource properties from the HMC and cache them in this Python object.
`pull_properties`(properties)	Retrieve the specified set of resource properties from the HMC and cache them in this Python object.
`update_properties_local`(properties)	Update the values of a set of resource properties on this Python object without propagating the updates to the HMC.

Attributes:

`ceased_existence`	Indicates that the corresponding object on the HMC no longer exists, if auto-update is enabled for the 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.

dump()[source]

Dump this Group resource with its properties as a resource definition.

The returned resource definition has the following format:

{
    # Resource properties:
    "properties": {...},
}

Returns:: Resource definition of this resource.
Return type:: dict

delete()[source]

Delete this Group.

Authorization requirements:

Object-access permission to this Group.
Task permission to the “Grouping” task.

Raises:

add_member(uri)[source]

Add a resource as a new member to the Group.

The group must be defined without a pattern-matching specification. The member resource must not already be a member of this group.

Authorization requirements:

Object-access permission to this Group.
Object-access permission to the resource that is added as a member.
Task permission to the “Grouping” task.

Parameters:

uri (string) – URI of the resource to be added.

Raises:

remove_member(uri)[source]

Remove a member resource from the Group.

The group must be defined without a pattern-matching specification. The resource must be a member of this group.

Authorization requirements:

Object-access permission to this Group.
Object-access permission to the resource that is added as a member.
Task permission to the “Grouping” task.

Parameters:

uri (string) – URI of the resource to be removed.

Raises:

list_members()[source]

List Group members.

Authorization requirements:

Object-access permission to this Group.
Object-access permission to each member resource of the Group.

Returns:

List of members. Each list item is a dictionary with items: - “object-uri” (term:string): URI of the member resource. - “name” (term:string): Name of the member resource.

Return type:

list

Raises:

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

reset_activation_profiles
image_activation_profiles
load_activation_profiles

Attributes:

`cpc`	CPC defining the scope for this manager.
`profile_type`	Type of the Activation Profiles managed by this object:
`case_insensitive_names`	`bool`: Indicates whether the names of the resources are treated case insensitively.
`class_name`	The resource class name
`name_prop`	The name of the resource property indicating the resource 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.
`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.
`uri`	The canonical URI path of the manager.

Methods:

`list`([full_properties, filter_args, ...])	List the Activation Profiles of this CPC, of the profile type managed by this object.
`create`(properties)	Create and configure an Activation Profiles on this CPC, of the profile type managed by this object.
`__repr__`()	Return a string with the state of this manager object, for debug purposes.
`add_resources_local`(resource_obj_list)	Add a resource object to the local auto-updated list of resources.
`auto_update_enabled`()	Return whether Auto-updating is currently enabled for the manager object.
`auto_update_needs_pull`()	Return whether there is a need to pull the resources from the HMC, in the list() method.
`auto_update_trigger_pull`()	Trigger the need to pull the resources from the HMC, in the list() method.
`disable_auto_update`()	Disable Auto-updating for this manager object, if currently enabled.
`dump`()	Dump the resources of this resource manager as a resource definition.
`enable_auto_update`()	Enable Auto-updating for this manager object, if currently disabled.
`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. for a CPC, a `Cpc` object is returned).
`find_by_name`(name)	Find a resource by name and return its Python resource object (e.g. for a CPC, a `Cpc` object is returned).
`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. for CPCs, a list of `Cpc` objects is returned).
`flush`()	Invalidate the Name-URI cache of this manager.
`invalidate_cache`()	Invalidate the Name-URI cache of this manager.
`list_resources_local`()	List the resource objects from the local auto-updated list of resources.
`remove_resource_local`(resource_uri)	Remove the resource object for a resource URI from the local auto-updated list of resources.
`resource_object`(uri_or_oid[, props])	Return a minimalistic Python resource object for this resource class, that is scoped to this manager.

property cpc

CPC defining the scope for this manager.

Type:: Cpc

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

list(full_properties=False, filter_args=None, additional_properties=None)[source]

List the Activation Profiles of this CPC, of the profile type managed by this object.

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, if the filter arguments specify the resource name as a single filter argument with a straight match string (i.e. without regular expressions), an optimized lookup is performed based on a locally maintained name-URI cache.
Otherwise, the HMC List operation is performed with the subset of the provided filter arguments that can be handled on the HMC side and the remaining filter arguments are applied on the client side on the list result.

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.
additional_properties (list of string) –
List of property names that are to be returned in addition to the default properties.

This parameter requires HMC 2.16.0 or higher, and is supported only for image profiles.

Returns:

A list of ActivationProfile objects.

Raises:

create(properties)[source]

Create and configure an Activation Profiles on this CPC, of the profile type managed by this object.

Supported only on z16 and later CPCs.

Authorization requirements:

Object-access permission to this CPC.
Task permission to the “Customize/Delete Activation Profiles” task.

Parameters:

properties (dict) –

Initial property values. Allowable properties are defined in section ‘Request body contents’ in section ‘Create Reset/Image/Load Activation Profile’ in the HMC API book.

Note that the input profile name for creation must be provided in property ‘profile-name’, even though it shows up on the created resource in property ‘name’. This applies to all three types of activation profiles.

Returns:

The resource object for the new Activation Profile. The object will have its ‘element-uri’ property set, and will also have the input properties set.

Return type:

ActivationProfile

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:

`delete`()	Delete this Activation Profile.
`update_properties`(properties)	Update writeable properties of this Activation Profile.
`assign_certificate`(certificate)	Assigns a Certificate to this Image Activation Profile.
`unassign_certificate`(certificate)	Unassign a Certificate from this Image 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-updating is currently enabled for the resource object.
`cease_existence_local`()	Update this Python object to indicate that the corresponding HMC object no longer exists.
`disable_auto_update`()	Disable Auto-updating for this resource object, if currently enabled.
`dump`()	Dump this resource with its properties and child resources (recursively) as a resource definition.
`enable_auto_update`()	Enable Auto-updating 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 cached in this Python object, without retrieving them from the HMC.
`get_properties_pulled`(names)	Return a set of resource properties with the values they currently have on 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 the resource does not have a property with that name.
`pull_full_properties`()	Retrieve the full set of resource properties from the HMC and cache them in this Python object.
`pull_properties`(properties)	Retrieve the specified set of resource properties from the HMC and cache them in this Python object.
`update_properties_local`(properties)	Update the values of a set of resource properties on this Python object without propagating the updates to the HMC.

Attributes:

`ceased_existence`	Indicates that the corresponding object on the HMC no longer exists, if auto-update is enabled for the 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.

delete()[source]

Delete this Activation Profile.

Supported only on z16 and later CPCs.

Authorization requirements:

Task permission to the “Customize/Delete Activation Profiles” task.

Raises:

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:

assign_certificate(certificate)[source]

Assigns a Certificate to this Image Activation Profile.

Feature enablement requirements:

“secure-boot-with-certificates” must be available on HMC and CPC

Authorization requirements:

Object-access permission to this Activation Profile.
Object-access permission to the specified certificate.
Task permission to the “Assign Secure Boot Certificates” task.

Parameters:

certificate (Certificate) – Certificate to be assigned. The certificate must not currently be assigned to this LPAR.

Raises:

unassign_certificate(certificate)[source]

Unassign a Certificate from this Image Activation Profile.

Feature enablement requirements:

“secure-boot-with-certificates” must be available on HMC and CPC

Authorization requirements:

Object-access permission to this Image Activation Profile.
Object-access permission to the specified certificate.
Task permission to the “Assign Secure Boot Certificates” task.

Parameters:

certificate (Certificate) – Certificate to be unassigned. The certificate must currently be assigned to this LPAR.

Raises:

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

lpars

Attributes:

`cpc`	CPC defining the scope for this manager.
`case_insensitive_names`	`bool`: Indicates whether the names of the resources are treated case insensitively.
`class_name`	The resource class name
`name_prop`	The name of the resource property indicating the resource 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.
`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.
`uri`	The canonical URI path of the manager.

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.
`add_resources_local`(resource_obj_list)	Add a resource object to the local auto-updated list of resources.
`auto_update_enabled`()	Return whether Auto-updating is currently enabled for the manager object.
`auto_update_needs_pull`()	Return whether there is a need to pull the resources from the HMC, in the list() method.
`auto_update_trigger_pull`()	Trigger the need to pull the resources from the HMC, in the list() method.
`disable_auto_update`()	Disable Auto-updating for this manager object, if currently enabled.
`dump`()	Dump the resources of this resource manager as a resource definition.
`enable_auto_update`()	Enable Auto-updating for this manager object, if currently disabled.
`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. for a CPC, a `Cpc` object is returned).
`find_by_name`(name)	Find a resource by name and return its Python resource object (e.g. for a CPC, a `Cpc` object is returned).
`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. for CPCs, a list of `Cpc` objects is returned).
`flush`()	Invalidate the Name-URI cache of this manager.
`invalidate_cache`()	Invalidate the Name-URI cache of this manager.
`list_resources_local`()	List the resource objects from the local auto-updated list of resources.
`remove_resource_local`(resource_uri)	Remove the resource object for a resource URI from the local auto-updated list of resources.
`resource_object`(uri_or_oid[, props])	Return a minimalistic Python resource object for this resource class, that is scoped to this manager.

property cpc

CPC defining the scope for this manager.

Type:: Cpc

list(full_properties=False, filter_args=None)[source]

List the LPARs in this CPC.

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, if the filter arguments specify the resource name as a single filter argument with a straight match string (i.e. without regular expressions), an optimized lookup is performed based on a locally maintained name-URI cache.
Otherwise, the HMC List operation is performed with the subset of the provided filter arguments that can be handled on the HMC side and the remaining filter arguments are applied on the client side on the list result.

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".
`nvme_load`(load_address[, load_parameter, ...])	Load (boot) this LPAR from a designated NVMe device, using the HMC operation "NVMe Load".
`nvme_dump`(load_address[, load_parameter, ...])	Load a standalone dump program from a designated NVMe device in this LPAR, using the HMC operation "NVMe Dump".
`load`([load_address, load_parameter, ...])	Load (boot) this LPAR from a load address (boot device), using the HMC operation "Load Logical Partition".
`load_from_ftp`(host, username, password, ...)	Load (boot) this LPAR from an FTP server, using the HMC operation "Load Logical Partition from FTP".
`stop`([wait_for_completion, ...])	Stop this LPAR, using the HMC operation "Stop Logical Partition".
`start`([wait_for_completion, ...])	Start this LPAR, using the HMC operation "Start Logical Partition".
`reset_clear`([force, wait_for_completion, ...])	Reset this LPAR and clears its memory.
`reset_normal`([force, wait_for_completion, ...])	Reset this LPAR without clearing its memory.
`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.
`list_os_messages`([begin, end, is_held, ...])	List all currently available operating system messages for 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.
`assign_certificate`(certificate)	Assigns a Certificate to this LPAR.
`unassign_certificate`(certificate)	Unassign a Certificate from this LPAR.
`__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-updating is currently enabled for the resource object.
`cease_existence_local`()	Update this Python object to indicate that the corresponding HMC object no longer exists.
`disable_auto_update`()	Disable Auto-updating for this resource object, if currently enabled.
`dump`()	Dump this resource with its properties and child resources (recursively) as a resource definition.
`enable_auto_update`()	Enable Auto-updating 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 cached in this Python object, without retrieving them from the HMC.
`get_properties_pulled`(names)	Return a set of resource properties with the values they currently have on 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 the resource does not have a property with that name.
`pull_full_properties`()	Retrieve the full set of resource properties from the HMC and cache them in this Python object.
`pull_properties`(properties)	Retrieve the specified set of resource properties from the HMC and cache them in this Python object.
`update_properties_local`(properties)	Update the values of a set of resource properties on this Python object without propagating the updates to the HMC.

Attributes:

`ceased_existence`	Indicates that the corresponding object on the HMC no longer exists, if auto-update is enabled for the 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.

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.

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 ‘Logical Partition object’ in the HMC API book.

Raises:

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 may take 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”.

The following approach is used to determine the desired state to wait for if wait_for_completion=True:

if the ‘operating-mode’ property of the image profile is ‘ssc’ or ‘zaware’, the desired state is “operating”.
if the profile specified in activation_profile_name is not the LPAR’s image profile, it is assumed to be a load profile and the desired state is “operating”.
if the ‘load-at-activation’ property of the image profile is True, the desired state is “operating”.
else, the desired state is “not-operating”.

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 status 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 load or image activation profile to be used instead of the one specified in the next-activation-profile-name property of the LPAR, or None.

If this parameter specifies an image activation profile, its name must match the LPAR name. For non-SSC partitions, the image profile’s load-at-activation property determines whether the activation is followed by a load of the control program using the load-related parameters from the image profile. SSC partitions are always auto-loaded (regardless of the load-at-activation property).

If this parameter specifies a load activation profile, the activation uses the image profile with the same name as the LPAR. The activation is always followed by a load of the control program (regardless of the image profile’s load-at-activation property) using the parameters from the load profile.

If this parameter is None, the next-activation-profile-name property of the LPAR will be used. That property can again specify an image profile or a load profile which are treated as described above. If that property is None, the image profile with the same name as the LPAR is used and is treated as described above.
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. This job does not support cancellation.

Return type:

None or Job

Raises:

HTTPError –
ParseError –
AuthError –
ConnectionError –
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 may take 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 “not-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 status 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. This job does not support cancellation.

Return type:

None or Job

Raises:

HTTPError –
ParseError –
AuthError –
ConnectionError –
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, os_ipl_token=None, clear_indicator=True)[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, and the HMC default of an empty string will be used.
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, and the HMC default of 0 will be used.
operating_system_specific_load_parameters (string) – Optional operating system specific load parameters to be used for the SCSI load. If empty string or None, it is not passed to the HMC, and the HMC default of an empty string will be used.
boot_record_logical_block_address (string) – Optional hexadecimal boot record logical block address to be used for the SCSI load. If None, it is not passed to the HMC, and the HMC default of “0” will be used.
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 status 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) – Boolean controlling whether the system checks the software signature of what is loaded against what the distributor signed it with. If False or None, it is not passed to the HMC, and the HMC default of False will be used. Requires the LPAR to be on a z15 or later.
os_ipl_token (string) – Optional hexadecimal value to be used for the SCSI load. If 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. If True or None, it is not passed to the HMC, and the HMC default of True will be used if the LPAR is on a z14 with SE version 2.14.1 or higher. Requires the LPAR to be on a z14 with SE version 2.14.1 or higher.

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. This job does not support cancellation.

Return type:

None or Job

Raises:

HTTPError –
ParseError –
AuthError –
ConnectionError –
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, secure_boot=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 dump.
load_parameter (string) – Optional load control string. If empty string or None, it is not passed to the HMC, and the HMC default of an empty string will be used.
disk_partition_id (integer) – Optional disk-partition-id (also called the boot program selector) to be used for the SCSI dump. If None, it is not passed to the HMC, and the HMC default of 0 will be used.
operating_system_specific_load_parameters (string) – Optional operating system specific load parameters to be used for the SCSI dump. If empty string or None, it is not passed to the HMC, and the HMC default of an empty string will be used.
boot_record_logical_block_address (string) – Optional hexadecimal boot record logical block address to be used for the SCSI dump. If None, it is not passed to the HMC, and the HMC default of “0” will be used.
os_ipl_token (string) – Optional hexadecimal value to be used for the SCSI dump. If None, it is not passed to the HMC.
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 status 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.
secure_boot (bool) – Boolean controlling whether the system checks the software signature of what is loaded against what the distributor signed it with. If False or None, it is not passed to the HMC, and the HMC default of False will be used. Requires the LPAR to be on a 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. This job does not support cancellation.

Return type:

None or Job

Raises:

HTTPError –
ParseError –
AuthError –
ConnectionError –
OperationTimeout – The timeout expired while waiting for completion of the operation.
StatusTimeout – The timeout expired while waiting for the desired LPAR status.

nvme_load(load_address, load_parameter=None, secure_boot=False, clear_indicator=True, 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)[source]

Load (boot) this LPAR from a designated NVMe device, using the HMC operation “NVMe Load”.

This operation requires z15 or later.

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.
Task permission for the “Load” task.

Parameters:

load_address (string) – Device number of the boot device.
load_parameter (string) – Optional load control string. If empty string or None, it is not passed to the HMC, and the HMC default of an empty string will be used.
secure_boot (bool) – Boolean controlling whether the system checks the software signature of what is loaded against what the distributor signed it with. If False or None, it is not passed to the HMC, and the HMC default of False will be used. Requires the LPAR to be on a z15 or later.
clear_indicator (bool) – Optional boolean controlling whether the memory should be cleared before performing the load or not cleared. If True or None, it is not passed to the HMC, and the HMC default of True will be used if the LPAR is on a z14 with SE version 2.14.1 or higher. Requires the LPAR to be on a z14 with SE version 2.14.1 or higher.
disk_partition_id (integer) – Optional disk-partition-id (also called the boot program selector) to be used for the NVMe Load. If None, it is not passed to the HMC, and the HMC default of 0 will be used.
operating_system_specific_load_parameters (string) – Optional operating system specific load parameters to be used for the NVMe Load. If empty string or None, it is not passed to the HMC, and the HMC default of an empty string will be used.
boot_record_logical_block_address (string) – Optional hexadecimal boot record logical block address to be used for the NVMe Load. If None, it is not passed to the HMC, and the HMC default of “0” will be used.
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 status 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. This job does not support cancellation.

Return type:

None or Job

Raises:

HTTPError –
ParseError –
AuthError –
ConnectionError –
OperationTimeout – The timeout expired while waiting for completion of the operation.
StatusTimeout – The timeout expired while waiting for the desired LPAR status.

nvme_dump(load_address, load_parameter=None, secure_boot=False, 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)[source]

Load a standalone dump program from a designated NVMe device in this LPAR, using the HMC operation “NVMe Dump”.

This operation requires z15 or later.

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.
Task permission for the “NVMe Dump” task.

Parameters:

load_address (string) – Device number of the boot device.
load_parameter (string) – Optional load control string. If empty string or None, it is not passed to the HMC, and the HMC default of an empty string will be used.
secure_boot (bool) – Boolean controlling whether the system checks the software signature of what is loaded against what the distributor signed it with. If False or None, it is not passed to the HMC, and the HMC default of False will be used. Requires the LPAR to be on a z15 or later.
disk_partition_id (integer) – Optional disk-partition-id (also called the boot program selector) to be used for the NVMe dump. If None, it is not passed to the HMC, and the HMC default of 0 will be used.
operating_system_specific_load_parameters (string) – Optional operating system specific load parameters to be used for the NVMe dump. If empty string or None, it is not passed to the HMC, and the HMC default of an empty string will be used.
boot_record_logical_block_address (string) – Optional hexadecimal boot record logical block address to be used for the NVMe dump. If None, it is not passed to the HMC, and the HMC default of “0” will be used.
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 status 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. This job does not support cancellation.

Return type:

None or Job

Raises:

HTTPError –
ParseError –
AuthError –
ConnectionError –
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, and the HMC default of an empty string will be used.
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 status 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. This job does not support cancellation.

Return type:

None or Job

Raises:

HTTPError –
ParseError –
AuthError –
ConnectionError –
OperationTimeout – The timeout expired while waiting for completion of the operation.
StatusTimeout – The timeout expired while waiting for the desired LPAR status.

load_from_ftp(host, username, password, load_file, protocol='ftp', wait_for_completion=True, operation_timeout=None, status_timeout=None, allow_status_exceptions=False)[source]

Load (boot) this LPAR from an FTP server, using the HMC operation “Load Logical Partition from FTP”.

This operation is not permitted for an LPAR whose ‘activation-mode’ property is “zaware” or “ssc”.

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 from Removable Media or Server” task.

Parameters:

host (string) – Host name or IP address of the FTP server.
username (string) – User name for the account on the FTP server.
password (string) – Password that is associated with the user name on the FTP server.
load_file (string) – Path name of the file to be read from the FTP server and loaded into the LPAR.
protocol (string) –
Network protocol for transferring files. Must be one of:
- ”ftp” - File Transfer Protocol
- ”ftps” - FTP Secure
- ”sftp” - SSH File Transfer Protocol
Default: “ftp”
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 status 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. This job does not support cancellation.

Return type:

None or Job

Raises:

HTTPError –
ParseError –
AuthError –
ConnectionError –
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 operation is not permitted for an LPAR whose ‘activation-mode’ property is “zaware” or “ssc”.

In order to succeed, the ‘status’ property of the LPAR must have one of the following values:

“not-operating”
“operating”
“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.
- 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) – Deprecated: This property was used for handling deferred status behavior, which is not actually needed. Setting it to a non-default value will cause a DeprecationWarning to be issued.
allow_status_exceptions (bool) – Deprecated: This property was used for handling deferred status behavior, which is not actually needed. Setting it to a non-default value will cause a DeprecationWarning to be issued.

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. This job does not support cancellation.

Return type:

None or Job

Raises:

HTTPError –
ParseError –
AuthError –
ConnectionError –
OperationTimeout – The timeout expired while waiting for completion of the operation.

start(wait_for_completion=True, operation_timeout=None, status_timeout=None, allow_status_exceptions=False)[source]

Start this LPAR, using the HMC operation “Start Logical Partition”. The start operation starts the processors to process instructions.

This operation is not permitted for an LPAR whose ‘activation-mode’ property is “zaware” or “ssc”.

In order to succeed, the ‘status’ property of the LPAR must have one of the following values:

“not-operating”
“operating”
“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 “Start” 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) – Deprecated: This property was used for handling deferred status behavior, which is not actually needed. Setting it to a non-default value will cause a DeprecationWarning to be issued.
allow_status_exceptions (bool) – Deprecated: This property was used for handling deferred status behavior, which is not actually needed. Setting it to a non-default value will cause a DeprecationWarning to be issued.

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 –
ParseError –
AuthError –
ConnectionError –
OperationTimeout – The timeout expired while waiting for completion of the operation.

reset_clear(force=False, wait_for_completion=True, operation_timeout=None, status_timeout=None, allow_status_exceptions=False, os_ipl_token=None)[source]

Reset this LPAR and clears its memory.

This includes clearing its pending interruptions, resetting its channel subsystem and resetting its processors, and clearing its memory, using the HMC operation “Reset Clear”.

In order to succeed, the ‘status’ property of the LPAR must have one of the following values:

“not-operating”
“operating” - this requires setting the “force” flag
“exceptions” - this requires setting the “force” flag

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.
- 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) – Deprecated: This property was used for handling deferred status behavior, which is not actually needed. Setting it to a non-default value will cause a DeprecationWarning to be issued.
allow_status_exceptions (bool) – Deprecated: This property was used for handling deferred status behavior, which is not actually needed. Setting it to a non-default value will cause a DeprecationWarning to be issued.
os_ipl_token (string) – Applicable only to z/OS, this parameter requests that this operation only be performed if the provided value matches the current value of the ‘os-ipl-token’ property of the LPAR.

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. This job does not support cancellation.

Return type:

None or Job

Raises:

HTTPError –
ParseError –
AuthError –
ConnectionError –
OperationTimeout – The timeout expired while waiting for completion of the operation.

reset_normal(force=False, wait_for_completion=True, operation_timeout=None, status_timeout=None, allow_status_exceptions=False, os_ipl_token=None)[source]

Reset this LPAR without clearing its memory.

This includes clearing its pending interruptions, resetting its channel subsystem and resetting its processors, using the HMC operation “Reset Normal”.

In order to succeed, the ‘status’ property of the LPAR must have one of the following values:

“not-operating”
“operating” - this requires setting the “force” flag
“exceptions” - this requires setting the “force” flag

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.
- 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) – Deprecated: This property was used for handling deferred status behavior, which is not actually needed. Setting it to a non-default value will cause a DeprecationWarning to be issued.
allow_status_exceptions (bool) – Deprecated: This property was used for handling deferred status behavior, which is not actually needed. Setting it to a non-default value will cause a DeprecationWarning to be issued.
os_ipl_token (string) – Applicable only to z/OS, this parameter requests that this operation only be performed if the provided value matches the current value of the ‘os-ipl-token’ property of the LPAR.

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. This job does not support cancellation.

Return type:

None or Job

Raises:

HTTPError –
ParseError –
AuthError –
ConnectionError –
OperationTimeout – The timeout expired while waiting for completion of the operation.

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:

string

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:

list_os_messages(begin=None, end=None, is_held=None, is_priority=None, max_messages=0)[source]

List all currently available operating system messages for this LPAR.

Only a certain amount of OS message data from each LPAR is preserved by the HMC for retrieval by this operation. If the OS produces more than that amount, the oldest non-held, non-priority OS messages are no longer available. A gap in the sequence numbers indicates a loss of messages. A loss may be due to that space limitation, or it may be due to the deletion of messages by a console user or the OS.

Authorization requirements:

Object-access permission to this LPAR.
Task permission to the “Operating System Messages” task (optionally in view-only mode).

Parameters:

begin (integer) – A message sequence number to limit returned messages. OS messages with a sequence number less than this are omitted from the results. If None, no such filtering is performed.
end (integer) – A message sequence number to limit returned messages. OS messages with a sequence number greater than this are omitted from the results. If None, no such filtering is performed.
is_held (bool) – Limit the returned messages to only held (if True) or only non-held (if False) messages. If None, no such filtering is performed.
is_priority (bool) – Limit the returned messages to only priority (if True) or non-priority (if False) messages. If None, no such filtering is performed.
max_messages (int) – Limits the returned messages to the specified maximum number, starting from the begin of the sequence numbers in the result that would otherwise be returned. If 0, no such filtering is performed.

Returns:

List of OS messages, where each OS message is a dict with the items defined for the “os-message-info” data structure in the HMC API book.

Return type:

list of dict

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”.

In order to succeed, the ‘status’ property of the LPAR must have one of the following values:

“not-operating”
“operating”
“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.
- 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) – Deprecated: This property was used for handling deferred status behavior, which is not actually needed. Setting it to a non-default value will cause a DeprecationWarning to be issued.
allow_status_exceptions (bool) – Deprecated: This property was used for handling deferred status behavior, which is not actually needed. Setting it to a non-default value will cause a DeprecationWarning to be issued.

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. This job does not support cancellation.

Return type:

None or Job

Raises:

HTTPError –
ParseError –
AuthError –
ConnectionError –
OperationTimeout – The timeout expired while waiting for completion of the operation.

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:

HTTPError –
ParseError –
AuthError –
ConnectionError –
StatusTimeout – The timeout expired while waiting for the desired LPAR status.

assign_certificate(certificate)[source]

Assigns a Certificate to this LPAR.

Feature enablement requirements:

“secure-boot-with-certificates” must be available on HMC and CPC

Authorization requirements:

Object-access permission to this LPAR.
Object-access permission to the specified certificate.
Task permission to the “Assign Secure Boot Certificates” task.

Parameters:

certificate (Certificate) – Certificate to be assigned. The certificate must not currently be assigned to this LPAR.

Raises:

unassign_certificate(certificate)[source]

Unassign a Certificate from this LPAR.

Feature enablement requirements:

“secure-boot-with-certificates” must be available on HMC and CPC

Authorization requirements:

Object-access permission to this LPAR.
Object-access permission to the specified certificate.
Task permission to the “Assign Secure Boot Certificates” task.

Parameters:

certificate (Certificate) – Certificate to be unassigned. The certificate must currently be assigned to this LPAR.

Raises:

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

partitions

Attributes:

`cpc`	CPC defining the scope for this manager.
`case_insensitive_names`	`bool`: Indicates whether the names of the resources are treated case insensitively.
`class_name`	The resource class name
`name_prop`	The name of the resource property indicating the resource 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.
`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.
`uri`	The canonical URI path of the manager.

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.
`add_resources_local`(resource_obj_list)	Add a resource object to the local auto-updated list of resources.
`auto_update_enabled`()	Return whether Auto-updating is currently enabled for the manager object.
`auto_update_needs_pull`()	Return whether there is a need to pull the resources from the HMC, in the list() method.
`auto_update_trigger_pull`()	Trigger the need to pull the resources from the HMC, in the list() method.
`disable_auto_update`()	Disable Auto-updating for this manager object, if currently enabled.
`dump`()	Dump the resources of this resource manager as a resource definition.
`enable_auto_update`()	Enable Auto-updating for this manager object, if currently disabled.
`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. for a CPC, a `Cpc` object is returned).
`find_by_name`(name)	Find a resource by name and return its Python resource object (e.g. for a CPC, a `Cpc` object is returned).
`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. for CPCs, a list of `Cpc` objects is returned).
`flush`()	Invalidate the Name-URI cache of this manager.
`invalidate_cache`()	Invalidate the Name-URI cache of this manager.
`list_resources_local`()	List the resource objects from the local auto-updated list of resources.
`remove_resource_local`(resource_uri)	Remove the resource object for a resource URI from the local auto-updated list of resources.
`resource_object`(uri_or_oid[, props])	Return a minimalistic Python resource object for this resource class, that is scoped to this manager.

property cpc

CPC defining the scope for this manager.

Type:: Cpc

list(full_properties=False, filter_args=None, additional_properties=None)[source]

List the Partitions in this CPC.

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, if the filter arguments specify the resource name as a single filter argument with a straight match string (i.e. without regular expressions), an optimized lookup is performed based on a locally maintained name-URI cache.
Otherwise, the HMC List operation is performed with the subset of the provided filter arguments that can be handled on the HMC side and the remaining filter arguments are applied on the client side on the list result.

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.
additional_properties (list of string) –
List of property names that are to be returned in addition to the default properties.

This parameter requires HMC 2.16.0 or higher.

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:

Partition

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:

`nics`	Access to the NICs in this Partition.
`hbas`	Access to the HBAs in this Partition.
`virtual_functions`	Access to the Virtual Functions in this Partition.
`ceased_existence`	Indicates that the corresponding object on the HMC no longer exists, if auto-update is enabled for the 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:

`feature_enabled`(feature_name)	Indicates whether the specified feature is enabled for the CPC of this partition.
`feature_info`()	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_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.
`list_os_messages`([begin, end])	List all currently available operating system messages for 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_crypto_domain_config`(...)	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.
`assign_certificate`(certificate)	Assigns a Certificate to this partition.
`unassign_certificate`(certificate)	Unassign a Certificate from this partition.
`dump`()	Dump this Partition resource with its properties and child resources (recursively) as a resource definition.
`__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-updating is currently enabled for the resource object.
`cease_existence_local`()	Update this Python object to indicate that the corresponding HMC object no longer exists.
`disable_auto_update`()	Disable Auto-updating for this resource object, if currently enabled.
`enable_auto_update`()	Enable Auto-updating 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 cached in this Python object, without retrieving them from the HMC.
`get_properties_pulled`(names)	Return a set of resource properties with the values they currently have on 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 the resource does not have a property with that name.
`pull_full_properties`()	Retrieve the full set of resource properties from the HMC and cache them in this Python object.
`pull_properties`(properties)	Retrieve the specified set of resource properties from the HMC and cache them in this Python object.
`update_properties_local`(properties)	Update the values of a set of resource properties on this Python object without propagating the updates to the HMC.

property nics

Access to the NICs in this Partition.

Type:: NicManager

property hbas

Access to the HBAs in this Partition.

If the “dpm-storage-management” feature is enabled (i.e. starting with z14), the CPC will not have any HBA objects anymore (they are now Virtual Storage Resources), but this property still provides a manager object for consistency.

Type:: HbaManager

property virtual_functions

Access to the Virtual Functions in this Partition.

Type:: VirtualFunctionManager

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:

bool

Raises:

ValueError – Features are not supported on the HMC.
ValueError – The specified feature is not available for the CPC.
HTTPError –
ParseError –
AuthError –
ConnectionError –

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:

iterable

Raises:

ValueError – Features are not supported on the HMC.
HTTPError –
ParseError –
AuthError –
ConnectionError –

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 status 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.

This job supports cancellation. Note that it may no longer be possible to cancel the job after some point. The job status and reason codes will indicate whether the job was canceled or ran to completion.

Return type:

dict or Job

Raises:

HTTPError –
ParseError –
AuthError –
ConnectionError –
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 status 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.

This job supports cancellation. Note that it may no longer be possible to cancel the job after some point. The job status and reason codes will indicate whether the job was canceled or ran to completion.

Return type:

dict or Job

Raises:

HTTPError –
ParseError –
AuthError –
ConnectionError –
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.

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 ‘Partition object’ in the HMC API book.

Raises:

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. This job does not support cancellation.

Return type:

dict or Job

Raises:

HTTPError –
ParseError –
AuthError –
ConnectionError –
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. This job does not support cancellation.

Return type:

dict or Job

Raises:

HTTPError –
ParseError –
AuthError –
ConnectionError –
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. This job does not support cancellation.

Return type:

dict or Job

Raises:

HTTPError –
ParseError –
AuthError –
ConnectionError –
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:

string

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:

list_os_messages(begin=None, end=None)[source]

List all currently available operating system messages for this partition.

Only a certain amount of OS message data from each partition is preserved by the HMC for retrieval by this operation. If the OS produces more than that amount, the oldest non-held, non-priority OS messages are no longer available. A gap in the sequence numbers indicates a loss of messages. A loss may be due to that space limitation, or it may be due to the deletion of messages by a console user or the OS.

Authorization requirements:

Object-access permission to this Partition.
Task permission to the “Operating System Messages” task (optionally in view-only mode).

Parameters:

begin (integer) – A message sequence number to limit returned messages. OS messages with a sequence number less than this are omitted from the results. If None, no such filtering is performed.
end (integer) – A message sequence number to limit returned messages. OS messages with a sequence number greater than this are omitted from the results. If None, no such filtering is performed.

Returns:

List of OS messages, where each OS message is a dict with the items defined for the “os-message-info” data structure in the HMC API book.

Return type:

list of dict

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:

HTTPError –
ParseError –
AuthError –
ConnectionError –
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:

crypto_adapter (Adapter) – Crypto adapter with the crypto domain to be zeroized.
crypto_domain_index (integer) – Domain index of the crypto domain to be zeroized.

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:

assign_certificate(certificate)[source]

Assigns a Certificate to this partition.

Feature enablement requirements:

“secure-boot-with-certificates” must be available on HMC and CPC

Authorization requirements:

Object-access permission to this partition.
Object-access permission to the specified certificate.
Task permission to the “Assign Secure Boot Certificates” task.

Parameters:

certificate (Certificate) – Certificate to be assigned. The certificate must not currently be assigned to this partition.

Raises:

unassign_certificate(certificate)[source]

Unassign a Certificate from this partition.

Feature enablement requirements:

“secure-boot-with-certificates” must be available on HMC and CPC

Authorization requirements:

Object-access permission to this partition.
Object-access permission to the specified certificate.
Task permission to the “Assign Secure Boot Certificates” task.

Parameters:

certificate (Certificate) – Certificate to be unassigned. The certificate must currently be assigned to this partition.

Raises:

dump()[source]

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

The returned resource definition has the following format:

{
    # Resource properties:
    "properties": {...},

    # Child resources:
    "nics": [...],
    "hbas": [...],
    "virtual_functions": [...],
}

Returns:: Resource definition of this resource.
Return type:: dict

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

adapters

Attributes:

`cpc`	CPC defining the scope for this manager.
`case_insensitive_names`	`bool`: Indicates whether the names of the resources are treated case insensitively.
`class_name`	The resource class name
`name_prop`	The name of the resource property indicating the resource 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.
`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.
`uri`	The canonical URI path of the manager.

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.
`add_resources_local`(resource_obj_list)	Add a resource object to the local auto-updated list of resources.
`auto_update_enabled`()	Return whether Auto-updating is currently enabled for the manager object.
`auto_update_needs_pull`()	Return whether there is a need to pull the resources from the HMC, in the list() method.
`auto_update_trigger_pull`()	Trigger the need to pull the resources from the HMC, in the list() method.
`disable_auto_update`()	Disable Auto-updating for this manager object, if currently enabled.
`dump`()	Dump the resources of this resource manager as a resource definition.
`enable_auto_update`()	Enable Auto-updating for this manager object, if currently disabled.
`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. for a CPC, a `Cpc` object is returned).
`find_by_name`(name)	Find a resource by name and return its Python resource object (e.g. for a CPC, a `Cpc` object is returned).
`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. for CPCs, a list of `Cpc` objects is returned).
`flush`()	Invalidate the Name-URI cache of this manager.
`invalidate_cache`()	Invalidate the Name-URI cache of this manager.
`list_resources_local`()	List the resource objects from the local auto-updated list of resources.
`remove_resource_local`(resource_uri)	Remove the resource object for a resource URI from the local auto-updated list of resources.
`resource_object`(uri_or_oid[, props])	Return a minimalistic Python resource object for this resource class, that is scoped to this manager.

property cpc

CPC defining the scope for this manager.

Type:: Cpc

list(full_properties=False, filter_args=None, additional_properties=None)[source]

List the Adapters in this CPC.

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, if the filter arguments specify the resource name as a single filter argument with a straight match string (i.e. without regular expressions), an optimized lookup is performed based on a locally maintained name-URI cache.
Otherwise, the HMC List operation is performed with the subset of the provided filter arguments that can be handled on the HMC side and the remaining filter arguments are applied on the client side on the list result.

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.
additional_properties (list of string) –
List of property names that are to be returned in addition to the default properties.

This parameter requires HMC 2.16.0 or higher.

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:

Adapter

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:

`ports`	Access to the Ports of this Adapter.
`port_uris_prop`	Name of adapter property that specifies the adapter port URIs, or the empty string ('') for adapters without ports.
`port_uri_segment`	Adapter type specific URI segment for adapter port URIs, or the empty string ('') for adapters without ports.
`maximum_crypto_domains`	The maximum number of crypto domains on this crypto adapter.
`ceased_existence`	Indicates that the corresponding object on the HMC no longer exists, if auto-update is enabled for the 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:

`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.
`dump`()	Dump this Adapter resource with its properties and child resources (recursively) as a resource definition.
`list_assigned_partitions`([full_properties, ...])	List the partitions assigned to this adapter.
`list_sibling_adapters`([full_properties])	List the other Adapters on the same adapter card as this Adapter.
`__str__`()	Return a human readable string representation of this resource.
`auto_update_enabled`()	Return whether Auto-updating is currently enabled for the resource object.
`cease_existence_local`()	Update this Python object to indicate that the corresponding HMC object no longer exists.
`disable_auto_update`()	Disable Auto-updating for this resource object, if currently enabled.
`enable_auto_update`()	Enable Auto-updating 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 cached in this Python object, without retrieving them from the HMC.
`get_properties_pulled`(names)	Return a set of resource properties with the values they currently have on 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 the resource does not have a property with that name.
`pull_full_properties`()	Retrieve the full set of resource properties from the HMC and cache them in this Python object.
`pull_properties`(properties)	Retrieve the specified set of resource properties from the HMC and cache them in this Python object.
`update_properties_local`(properties)	Update the values of a set of resource properties on this Python object without propagating the updates to the HMC.

property ports

Access to the Ports of this Adapter.

Type:: PortManager

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

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

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	z15 (5) / z14 (3) / z13 (1)	85
Crypto Express 5S	z15 (6) / z14-ZR1 (4) / z13s (2)	40
Crypto Express 6S	z16 (7) / z15 (5) / z14 (3)	85
Crypto Express 6S	z15 (6) / z14-ZR1 (4)	40
Crypto Express 7S	z16 (7) / z15 (5)	85
Crypto Express 7S	z15 (6)	40
Crypto Express 8S	z16 (7)	85

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-T01 and LinuxONE III LT1
Supported for z15-T02 and LinuxONE III LT2
Supported for z16-A01 and LinuxONE 4

If this adapter is not a crypto adapter, None is returned.

If the crypto adapter card type is not known, ValueError is raised.

Raises:

HTTPError –
ParseError –
AuthError –
ConnectionError –
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.

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 ‘Adapter object’ in the HMC API book.

Raises:

__repr__()[source]: Return a string with the state of this Adapter, for debug purposes.

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:

dump()[source]

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

The returned resource definition has the following format:

{
    # Resource properties:
    "properties": {...},

    # Child resources:
    "ports": [...],
}

Returns:: Resource definition of this resource.
Return type:: dict

list_assigned_partitions(full_properties=False, filter_args=None)[source]

List the partitions assigned to this adapter.

This method is not supported for OSA adapters configured as OSM (because those cannot be assigned to partitions).

Authorization requirements:

Object-access permission to this Adapter.

Parameters:

full_properties (bool) – Controls whether the full set of partition properties should be retrieved, vs. only a short set (uri, name, status).
filter_args (dict) –
Filter arguments that narrow the list of returned partitions to those that match the specified filter arguments. For details, see Filtering.

None causes no filtering to happen, i.e. all assigned partitions are returned.

Returns:

A list of Partition objects.

Raises:

list_sibling_adapters(full_properties=False)[source]

List the other Adapters on the same adapter card as this Adapter.

Some adapter cards are represented as multiple Adapter objects (for example, 2-port FICON Express cards, or 2-port CNA cards). This method lists the other Adapter objects that are on the same adapter card as this Adapter object.

This is useful for example to determine the affected Adapter objects when replacing the adapter card, or when changing the type of a FICON Express adepter (see change_adapter_type()).

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.

Returns:

A list of Adapter objects.

Raises:

5.8. 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`	Adapter defining the scope for this manager.
`port_type`	Type of the Ports managed by this object:
`case_insensitive_names`	`bool`: Indicates whether the names of the resources are treated case insensitively.
`class_name`	The resource class name
`name_prop`	The name of the resource property indicating the resource 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.
`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.
`uri`	The canonical URI path of the manager.

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.
`add_resources_local`(resource_obj_list)	Add a resource object to the local auto-updated list of resources.
`auto_update_enabled`()	Return whether Auto-updating is currently enabled for the manager object.
`auto_update_needs_pull`()	Return whether there is a need to pull the resources from the HMC, in the list() method.
`auto_update_trigger_pull`()	Trigger the need to pull the resources from the HMC, in the list() method.
`disable_auto_update`()	Disable Auto-updating for this manager object, if currently enabled.
`dump`()	Dump the resources of this resource manager as a resource definition.
`enable_auto_update`()	Enable Auto-updating for this manager object, if currently disabled.
`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. for a CPC, a `Cpc` object is returned).
`find_by_name`(name)	Find a resource by name and return its Python resource object (e.g. for a CPC, a `Cpc` object is returned).
`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. for CPCs, a list of `Cpc` objects is returned).
`flush`()	Invalidate the Name-URI cache of this manager.
`invalidate_cache`()	Invalidate the Name-URI cache of this manager.
`list_resources_local`()	List the resource objects from the local auto-updated list of resources.
`remove_resource_local`(resource_uri)	Remove the resource object for a resource URI from the local auto-updated list of resources.
`resource_object`(uri_or_oid[, props])	Return a minimalistic Python resource object for this resource class, that is scoped to this manager.

property adapter

Adapter defining the scope for this manager.

Type:: Adapter

property port_type

Type of the Ports managed by this object:

'network' - Ports of a network adapter
'storage' - Ports of a storage adapter
None - Adapter family without ports

Type:: string

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.

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, if the filter arguments specify the resource name as a single filter argument with a straight match string (i.e. without regular expressions), an optimized lookup is performed based on a locally maintained name-URI cache.
Otherwise, the corresponding array property for this resource in the parent object is used to list the resources, and the provided filter arguments are applied.

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.
`dump`()	Dump the Port resource with its properties as a resource definition.
`__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-updating is currently enabled for the resource object.
`cease_existence_local`()	Update this Python object to indicate that the corresponding HMC object no longer exists.
`disable_auto_update`()	Disable Auto-updating for this resource object, if currently enabled.
`enable_auto_update`()	Enable Auto-updating 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 cached in this Python object, without retrieving them from the HMC.
`get_properties_pulled`(names)	Return a set of resource properties with the values they currently have on 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 the resource does not have a property with that name.
`pull_full_properties`()	Retrieve the full set of resource properties from the HMC and cache them in this Python object.
`pull_properties`(properties)	Retrieve the specified set of resource properties from the HMC and cache them in this Python object.
`update_properties_local`(properties)	Update the values of a set of resource properties on this Python object without propagating the updates to the HMC.

Attributes:

`ceased_existence`	Indicates that the corresponding object on the HMC no longer exists, if auto-update is enabled for the 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.

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.

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 - Port Element Object’ in the HMC API book.

Raises:

dump()[source]

Dump the Port resource with its properties as a resource definition.

If the adapter of this port is a FICON adapter in the not-configured state, the port properties cannot be retrieved from the HMC, so an empty dict is returned.

Otherwise, the returned resource definition has the following format:

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

Returns:: Resource definition of this Port resource.
Return type:: dict

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

nics

Attributes:

`partition`	Partition defining the scope for this manager.
`case_insensitive_names`	`bool`: Indicates whether the names of the resources are treated case insensitively.
`class_name`	The resource class name
`name_prop`	The name of the resource property indicating the resource 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.
`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.
`uri`	The canonical URI path of the manager.

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.
`add_resources_local`(resource_obj_list)	Add a resource object to the local auto-updated list of resources.
`auto_update_enabled`()	Return whether Auto-updating is currently enabled for the manager object.
`auto_update_needs_pull`()	Return whether there is a need to pull the resources from the HMC, in the list() method.
`auto_update_trigger_pull`()	Trigger the need to pull the resources from the HMC, in the list() method.
`disable_auto_update`()	Disable Auto-updating for this manager object, if currently enabled.
`dump`()	Dump the resources of this resource manager as a resource definition.
`enable_auto_update`()	Enable Auto-updating for this manager object, if currently disabled.
`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. for a CPC, a `Cpc` object is returned).
`find_by_name`(name)	Find a resource by name and return its Python resource object (e.g. for a CPC, a `Cpc` object is returned).
`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. for CPCs, a list of `Cpc` objects is returned).
`flush`()	Invalidate the Name-URI cache of this manager.
`invalidate_cache`()	Invalidate the Name-URI cache of this manager.
`list_resources_local`()	List the resource objects from the local auto-updated list of resources.
`remove_resource_local`(resource_uri)	Remove the resource object for a resource URI from the local auto-updated list of resources.
`resource_object`(uri_or_oid[, props])	Return a minimalistic Python resource object for this resource class, that is scoped to this manager.

property partition

Partition defining the scope for this manager.

Type:: Partition

list(full_properties=False, filter_args=None)[source]

List the NICs in this Partition.

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, if the filter arguments specify the resource name as a single filter argument with a straight match string (i.e. without regular expressions), an optimized lookup is performed based on a locally maintained name-URI cache.
Otherwise, the corresponding array property for this resource in the parent object is used to list the resources, and the provided filter arguments are applied.

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:

Nic

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.
`backing_port`()	Return the backing adapter port of the 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-updating is currently enabled for the resource object.
`cease_existence_local`()	Update this Python object to indicate that the corresponding HMC object no longer exists.
`disable_auto_update`()	Disable Auto-updating for this resource object, if currently enabled.
`dump`()	Dump this resource with its properties and child resources (recursively) as a resource definition.
`enable_auto_update`()	Enable Auto-updating 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 cached in this Python object, without retrieving them from the HMC.
`get_properties_pulled`(names)	Return a set of resource properties with the values they currently have on 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 the resource does not have a property with that name.
`pull_full_properties`()	Retrieve the full set of resource properties from the HMC and cache them in this Python object.
`pull_properties`(properties)	Retrieve the specified set of resource properties from the HMC and cache them in this Python object.
`update_properties_local`(properties)	Update the values of a set of resource properties on this Python object without propagating the updates to the HMC.

Attributes:

`ceased_existence`	Indicates that the corresponding object on the HMC no longer exists, if auto-update is enabled for the 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.

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.

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 - NIC Element Object’ in the HMC API book.

Raises:

backing_port()[source]

Return the backing adapter port of the NIC.

For vswitch-based NICs (e.g. OSA, HiperSocket), the NIC references the backing vswitch which references its backing adapter and port index. In this case, ‘Retrieve … Properties’ operations are performed for the vswitch, the adapter and the port.

For port-based NICs (e.g. RoCE, CNA), the NIC references directly the backing port. In this case, ‘Retrieve … Properties’ operations are performed for the port and the adapter.

Returns:

A resource object for the backing adapter port.

Return type:

Port

Raises:

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

hbas

Note that this instance variable will be None if the “dpm-storage-management” feature is enabled.

Attributes:

`partition`	Partition defining the scope for this manager.
`case_insensitive_names`	`bool`: Indicates whether the names of the resources are treated case insensitively.
`class_name`	The resource class name
`name_prop`	The name of the resource property indicating the resource 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.
`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.
`uri`	The canonical URI path of the manager.

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.
`add_resources_local`(resource_obj_list)	Add a resource object to the local auto-updated list of resources.
`auto_update_enabled`()	Return whether Auto-updating is currently enabled for the manager object.
`auto_update_needs_pull`()	Return whether there is a need to pull the resources from the HMC, in the list() method.
`auto_update_trigger_pull`()	Trigger the need to pull the resources from the HMC, in the list() method.
`disable_auto_update`()	Disable Auto-updating for this manager object, if currently enabled.
`dump`()	Dump the resources of this resource manager as a resource definition.
`enable_auto_update`()	Enable Auto-updating for this manager object, if currently disabled.
`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. for a CPC, a `Cpc` object is returned).
`find_by_name`(name)	Find a resource by name and return its Python resource object (e.g. for a CPC, a `Cpc` object is returned).
`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. for CPCs, a list of `Cpc` objects is returned).
`flush`()	Invalidate the Name-URI cache of this manager.
`invalidate_cache`()	Invalidate the Name-URI cache of this manager.
`list_resources_local`()	List the resource objects from the local auto-updated list of resources.
`remove_resource_local`(resource_uri)	Remove the resource object for a resource URI from the local auto-updated list of resources.
`resource_object`(uri_or_oid[, props])	Return a minimalistic Python resource object for this resource class, that is scoped to this manager.

property partition

Partition defining the scope for this manager.

Type:: Partition

list(full_properties=False, filter_args=None)[source]

List the HBAs in this Partition.

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, if the filter arguments specify the resource name as a single filter argument with a straight match string (i.e. without regular expressions), an optimized lookup is performed based on a locally maintained name-URI cache.
Otherwise, the corresponding array property for this resource in the parent object is used to list the resources, and the provided filter arguments are applied.

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:

Hba

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-updating is currently enabled for the resource object.
`cease_existence_local`()	Update this Python object to indicate that the corresponding HMC object no longer exists.
`disable_auto_update`()	Disable Auto-updating for this resource object, if currently enabled.
`dump`()	Dump this resource with its properties and child resources (recursively) as a resource definition.
`enable_auto_update`()	Enable Auto-updating 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 cached in this Python object, without retrieving them from the HMC.
`get_properties_pulled`(names)	Return a set of resource properties with the values they currently have on 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 the resource does not have a property with that name.
`pull_full_properties`()	Retrieve the full set of resource properties from the HMC and cache them in this Python object.
`pull_properties`(properties)	Retrieve the specified set of resource properties from the HMC and cache them in this Python object.
`update_properties_local`(properties)	Update the values of a set of resource properties on this Python object without propagating the updates to the HMC.

Attributes:

`ceased_existence`	Indicates that the corresponding object on the HMC no longer exists, if auto-update is enabled for the 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.

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.

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 - HBA Element Object’ in the HMC API book.

Raises:

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.

Parameters:

port (Port) – FCP port to be used.

Raises:

HTTPError – See the HTTP status and reason codes of operation “Reassign Storage Adapter Port” in the HMC API book.
ParseError –
AuthError –
ConnectionError –

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

virtual_functions

Attributes:

`partition`	Partition defining the scope for this manager.
`case_insensitive_names`	`bool`: Indicates whether the names of the resources are treated case insensitively.
`class_name`	The resource class name
`name_prop`	The name of the resource property indicating the resource 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.
`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.
`uri`	The canonical URI path of the manager.

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.
`add_resources_local`(resource_obj_list)	Add a resource object to the local auto-updated list of resources.
`auto_update_enabled`()	Return whether Auto-updating is currently enabled for the manager object.
`auto_update_needs_pull`()	Return whether there is a need to pull the resources from the HMC, in the list() method.
`auto_update_trigger_pull`()	Trigger the need to pull the resources from the HMC, in the list() method.
`disable_auto_update`()	Disable Auto-updating for this manager object, if currently enabled.
`dump`()	Dump the resources of this resource manager as a resource definition.
`enable_auto_update`()	Enable Auto-updating for this manager object, if currently disabled.
`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. for a CPC, a `Cpc` object is returned).
`find_by_name`(name)	Find a resource by name and return its Python resource object (e.g. for a CPC, a `Cpc` object is returned).
`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. for CPCs, a list of `Cpc` objects is returned).
`flush`()	Invalidate the Name-URI cache of this manager.
`invalidate_cache`()	Invalidate the Name-URI cache of this manager.
`list_resources_local`()	List the resource objects from the local auto-updated list of resources.
`remove_resource_local`(resource_uri)	Remove the resource object for a resource URI from the local auto-updated list of resources.
`resource_object`(uri_or_oid[, props])	Return a minimalistic Python resource object for this resource class, that is scoped to this manager.

property partition

Partition defining the scope for this manager.

Type:: Partition

list(full_properties=False, filter_args=None)[source]

List the Virtual Functions of this Partition.

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, if the filter arguments specify the resource name as a single filter argument with a straight match string (i.e. without regular expressions), an optimized lookup is performed based on a locally maintained name-URI cache.
Otherwise, the corresponding array property for this resource in the parent object is used to list the resources, and the provided filter arguments are applied.

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:

VirtualFunction

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-updating is currently enabled for the resource object.
`cease_existence_local`()	Update this Python object to indicate that the corresponding HMC object no longer exists.
`disable_auto_update`()	Disable Auto-updating for this resource object, if currently enabled.
`dump`()	Dump this resource with its properties and child resources (recursively) as a resource definition.
`enable_auto_update`()	Enable Auto-updating 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 cached in this Python object, without retrieving them from the HMC.
`get_properties_pulled`(names)	Return a set of resource properties with the values they currently have on 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 the resource does not have a property with that name.
`pull_full_properties`()	Retrieve the full set of resource properties from the HMC and cache them in this Python object.
`pull_properties`(properties)	Retrieve the specified set of resource properties from the HMC and cache them in this Python object.
`update_properties_local`(properties)	Update the values of a set of resource properties on this Python object without propagating the updates to the HMC.

Attributes:

`ceased_existence`	Indicates that the corresponding object on the HMC no longer exists, if auto-update is enabled for the 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.

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.

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 - Virtual Function element object’ in the HMC API book.

Raises:

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

virtual_switches

Attributes:

`cpc`	CPC defining the scope for this manager.
`case_insensitive_names`	`bool`: Indicates whether the names of the resources are treated case insensitively.
`class_name`	The resource class name
`name_prop`	The name of the resource property indicating the resource 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.
`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.
`uri`	The canonical URI path of the manager.

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.
`add_resources_local`(resource_obj_list)	Add a resource object to the local auto-updated list of resources.
`auto_update_enabled`()	Return whether Auto-updating is currently enabled for the manager object.
`auto_update_needs_pull`()	Return whether there is a need to pull the resources from the HMC, in the list() method.
`auto_update_trigger_pull`()	Trigger the need to pull the resources from the HMC, in the list() method.
`disable_auto_update`()	Disable Auto-updating for this manager object, if currently enabled.
`dump`()	Dump the resources of this resource manager as a resource definition.
`enable_auto_update`()	Enable Auto-updating for this manager object, if currently disabled.
`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. for a CPC, a `Cpc` object is returned).
`find_by_name`(name)	Find a resource by name and return its Python resource object (e.g. for a CPC, a `Cpc` object is returned).
`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. for CPCs, a list of `Cpc` objects is returned).
`flush`()	Invalidate the Name-URI cache of this manager.
`invalidate_cache`()	Invalidate the Name-URI cache of this manager.
`list_resources_local`()	List the resource objects from the local auto-updated list of resources.
`remove_resource_local`(resource_uri)	Remove the resource object for a resource URI from the local auto-updated list of resources.
`resource_object`(uri_or_oid[, props])	Return a minimalistic Python resource object for this resource class, that is scoped to this manager.

property cpc

CPC defining the scope for this manager.

Type:: Cpc

list(full_properties=False, filter_args=None, additional_properties=None)[source]

List the Virtual Switches in this CPC.

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, if the filter arguments specify the resource name as a single filter argument with a straight match string (i.e. without regular expressions), an optimized lookup is performed based on a locally maintained name-URI cache.
Otherwise, the HMC List operation is performed with the subset of the provided filter arguments that can be handled on the HMC side and the remaining filter arguments are applied on the client side on the list result.

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.
additional_properties (list of string) –
List of property names that are to be returned in addition to the default properties.

This parameter requires HMC 2.16.0 or higher.

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:

`get_connected_nics`()	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-updating is currently enabled for the resource object.
`cease_existence_local`()	Update this Python object to indicate that the corresponding HMC object no longer exists.
`disable_auto_update`()	Disable Auto-updating for this resource object, if currently enabled.
`dump`()	Dump this resource with its properties and child resources (recursively) as a resource definition.
`enable_auto_update`()	Enable Auto-updating 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 cached in this Python object, without retrieving them from the HMC.
`get_properties_pulled`(names)	Return a set of resource properties with the values they currently have on 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 the resource does not have a property with that name.
`pull_full_properties`()	Retrieve the full set of resource properties from the HMC and cache them in this Python object.
`pull_properties`(properties)	Retrieve the specified set of resource properties from the HMC and cache them in this Python object.
`update_properties_local`(properties)	Update the values of a set of resource properties on this Python object without propagating the updates to the HMC.

Attributes:

`ceased_existence`	Indicates that the corresponding object on the HMC no longer exists, if auto-update is enabled for the 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.

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.

Returns:

A list of Nic objects. These objects will be connected in the resource tree (i.e. have a parent Partition object, etc.) and will have the following properties set:

element-uri
element-id
parent
class

Raises:

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.

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 ‘Virtual Switch object’ in the HMC API book.

Raises:

5.13. 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 a Console object.

Attributes:

`console`	The Console object representing the HMC.
`case_insensitive_names`	`bool`: Indicates whether the names of the resources are treated case insensitively.
`class_name`	The resource class name
`name_prop`	The name of the resource property indicating the resource 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.
`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.
`uri`	The canonical URI path of the manager.

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.
`add_resources_local`(resource_obj_list)	Add a resource object to the local auto-updated list of resources.
`auto_update_enabled`()	Return whether Auto-updating is currently enabled for the manager object.
`auto_update_needs_pull`()	Return whether there is a need to pull the resources from the HMC, in the list() method.
`auto_update_trigger_pull`()	Trigger the need to pull the resources from the HMC, in the list() method.
`disable_auto_update`()	Disable Auto-updating for this manager object, if currently enabled.
`dump`()	Dump the resources of this resource manager as a resource definition.
`enable_auto_update`()	Enable Auto-updating for this manager object, if currently disabled.
`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. for a CPC, a `Cpc` object is returned).
`find_by_name`(name)	Find a resource by name and return its Python resource object (e.g. for a CPC, a `Cpc` object is returned).
`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. for CPCs, a list of `Cpc` objects is returned).
`flush`()	Invalidate the Name-URI cache of this manager.
`invalidate_cache`()	Invalidate the Name-URI cache of this manager.
`list_resources_local`()	List the resource objects from the local auto-updated list of resources.
`remove_resource_local`(resource_uri)	Remove the resource object for a resource URI from the local auto-updated list of resources.
`resource_object`(uri_or_oid[, props])	Return a minimalistic Python resource object for this resource class, that is scoped to this manager.

property console

The Console object representing the HMC.

Type:: Console

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.

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, if the filter arguments specify the resource name as a single filter argument with a straight match string (i.e. without regular expressions), an optimized lookup is performed based on a locally maintained name-URI cache.
Otherwise, the HMC List operation is performed with the subset of the provided filter arguments that can be handled on the HMC side and the remaining filter arguments are applied on the client side on the list result.

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:

StorageGroup

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:

`storage_volumes`	Access to the storage volumes in this storage group.
`virtual_storage_resources`	Access to the virtual storage resources in this storage group.
`cpc`	The CPC to which this storage group is associated.
`ceased_existence`	Indicates that the corresponding object on the HMC no longer exists, if auto-update is enabled for the 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:

`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. zones on a SAN switch, or host objects on a storage subsystem).
`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_candidate_adapter_ports`(ports)	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 FCP storage group.
`discover_fcp`([force_restart, ...])	Perform Logical Unit Number (LUN) discovery for this FCP storage group.
`get_connection_report`()	Get the latest connection report for this storage group.
`dump`()	Dump this StorageGroup resource with its properties and child resources (recursively) as a resource definition.
`__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-updating is currently enabled for the resource object.
`cease_existence_local`()	Update this Python object to indicate that the corresponding HMC object no longer exists.
`disable_auto_update`()	Disable Auto-updating for this resource object, if currently enabled.
`enable_auto_update`()	Enable Auto-updating 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 cached in this Python object, without retrieving them from the HMC.
`get_properties_pulled`(names)	Return a set of resource properties with the values they currently have on 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 the resource does not have a property with that name.
`pull_full_properties`()	Retrieve the full set of resource properties from the HMC and cache them in this Python object.
`pull_properties`(properties)	Retrieve the specified set of resource properties from the HMC and cache them in this Python object.
`update_properties_local`(properties)	Update the values of a set of resource properties on this Python object without propagating the updates to the HMC.

property storage_volumes

Access to the storage volumes in this storage group.

Type:: StorageVolumeManager

property virtual_storage_resources

Access to the virtual storage resources in this storage group.

Type:: VirtualStorageResourceManager

property cpc

The CPC to which this storage group is associated.

The returned Cpc has only a minimal set of properties populated.

Type:: Cpc

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:

HTTPError –
ParseError –
AuthError –
ConnectionError –
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, each StorageVolume resource can individually be created, deleted and updated using the respective methods on storage_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.

Parameters:

ports (list) – List of Port objects representing the ports to be added. All specified ports must not already be members of this storage group’s candidate adapter ports list.

Raises:

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.

Parameters:

ports (list) – List of Port objects representing the ports to be removed. All specified ports must currently be members of this storage group’s candidate adapter ports list and must not be referenced by any of the group’s virtual storage resources.

Raises:

list_candidate_adapter_ports(full_properties=False)[source]

Return the current candidate storage adapter port list of this FCP storage group.

This operation only applies to storage groups of type “fcp”.

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. This job does not support cancellation.

Return type:

None or Job

Raises:

HTTPError –
ParseError –
AuthError –
ConnectionError –
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:

json object

Raises:

dump()[source]

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

The returned resource definition has the following format:

{
    # Resource properties:
    "properties": {...},

    # Child resources:
    "storage_volumes": [...],
}

Returns:: Resource definition of this resource.
Return type:: dict

5.14. 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:

storage_volumes

Attributes:

`storage_group`	Storage group defining the scope for this manager.
`case_insensitive_names`	`bool`: Indicates whether the names of the resources are treated case insensitively.
`class_name`	The resource class name
`name_prop`	The name of the resource property indicating the resource 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.
`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.
`uri`	The canonical URI path of the manager.

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. LUN mask definition on the storage subsystem).
`__repr__`()	Return a string with the state of this manager object, for debug purposes.
`add_resources_local`(resource_obj_list)	Add a resource object to the local auto-updated list of resources.
`auto_update_enabled`()	Return whether Auto-updating is currently enabled for the manager object.
`auto_update_needs_pull`()	Return whether there is a need to pull the resources from the HMC, in the list() method.
`auto_update_trigger_pull`()	Trigger the need to pull the resources from the HMC, in the list() method.
`disable_auto_update`()	Disable Auto-updating for this manager object, if currently enabled.
`dump`()	Dump the resources of this resource manager as a resource definition.
`enable_auto_update`()	Enable Auto-updating for this manager object, if currently disabled.
`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. for a CPC, a `Cpc` object is returned).
`find_by_name`(name)	Find a resource by name and return its Python resource object (e.g. for a CPC, a `Cpc` object is returned).
`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. for CPCs, a list of `Cpc` objects is returned).
`flush`()	Invalidate the Name-URI cache of this manager.
`invalidate_cache`()	Invalidate the Name-URI cache of this manager.
`list_resources_local`()	List the resource objects from the local auto-updated list of resources.
`remove_resource_local`(resource_uri)	Remove the resource object for a resource URI from the local auto-updated list of resources.
`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:: StorageGroup

list(full_properties=False, filter_args=None)[source]

List the storage volumes in this storage group.

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, if the filter arguments specify the resource name as a single filter argument with a straight match string (i.e. without regular expressions), an optimized lookup is performed based on a locally maintained name-URI cache.
Otherwise, the HMC List operation is performed with the subset of the provided filter arguments that can be handled on the HMC side and the remaining filter arguments are applied on the client side on the list result.

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:

StorageVolume

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:

`oid`	term unicode string: The object ID of this storage volume.
`ceased_existence`	Indicates that the corresponding object on the HMC no longer exists, if auto-update is enabled for the 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:

`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. LUN mask definitions on a storage subsystem).
`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-updating is currently enabled for the resource object.
`cease_existence_local`()	Update this Python object to indicate that the corresponding HMC object no longer exists.
`disable_auto_update`()	Disable Auto-updating for this resource object, if currently enabled.
`dump`()	Dump this resource with its properties and child resources (recursively) as a resource definition.
`enable_auto_update`()	Enable Auto-updating 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 cached in this Python object, without retrieving them from the HMC.
`get_properties_pulled`(names)	Return a set of resource properties with the values they currently have on 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 the resource does not have a property with that name.
`pull_full_properties`()	Retrieve the full set of resource properties from the HMC and cache them in this Python object.
`pull_properties`(properties)	Retrieve the specified set of resource properties from the HMC and cache them in this Python object.
`update_properties_local`(properties)	Update the values of a set of resource properties on this Python object without propagating the updates to 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:

5.15. 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:

virtual_storage_resources

Attributes:

`storage_group`	Storage group defining the scope for this manager.
`case_insensitive_names`	`bool`: Indicates whether the names of the resources are treated case insensitively.
`class_name`	The resource class name
`name_prop`	The name of the resource property indicating the resource 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.
`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.
`uri`	The canonical URI path of the manager.

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.
`add_resources_local`(resource_obj_list)	Add a resource object to the local auto-updated list of resources.
`auto_update_enabled`()	Return whether Auto-updating is currently enabled for the manager object.
`auto_update_needs_pull`()	Return whether there is a need to pull the resources from the HMC, in the list() method.
`auto_update_trigger_pull`()	Trigger the need to pull the resources from the HMC, in the list() method.
`disable_auto_update`()	Disable Auto-updating for this manager object, if currently enabled.
`dump`()	Dump the resources of this resource manager as a resource definition.
`enable_auto_update`()	Enable Auto-updating for this manager object, if currently disabled.
`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. for a CPC, a `Cpc` object is returned).
`find_by_name`(name)	Find a resource by name and return its Python resource object (e.g. for a CPC, a `Cpc` object is returned).
`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. for CPCs, a list of `Cpc` objects is returned).
`flush`()	Invalidate the Name-URI cache of this manager.
`invalidate_cache`()	Invalidate the Name-URI cache of this manager.
`list_resources_local`()	List the resource objects from the local auto-updated list of resources.
`remove_resource_local`(resource_uri)	Remove the resource object for a resource URI from the local auto-updated list of resources.
`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:: StorageGroup

list(full_properties=False, filter_args=None)[source]

List the virtual storage resources in this storage group.

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, if the filter arguments specify the resource name as a single filter argument with a straight match string (i.e. without regular expressions), an optimized lookup is performed based on a locally maintained name-URI cache.
Otherwise, the HMC List operation is performed with the subset of the provided filter arguments that can be handled on the HMC side and the remaining filter arguments are applied on the client side on the list result.

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:

`attached_partition`	The partition to which this virtual storage resource is attached.
`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.
`ceased_existence`	Indicates that the corresponding object on the HMC no longer exists, if auto-update is enabled for the 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-updating is currently enabled for the resource object.
`cease_existence_local`()	Update this Python object to indicate that the corresponding HMC object no longer exists.
`disable_auto_update`()	Disable Auto-updating for this resource object, if currently enabled.
`dump`()	Dump this resource with its properties and child resources (recursively) as a resource definition.
`enable_auto_update`()	Enable Auto-updating 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 cached in this Python object, without retrieving them from the HMC.
`get_properties_pulled`(names)	Return a set of resource properties with the values they currently have on 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 the resource does not have a property with that name.
`pull_full_properties`()	Retrieve the full set of resource properties from the HMC and cache them in this Python object.
`pull_properties`(properties)	Retrieve the specified set of resource properties from the HMC and cache them in this Python object.
`update_properties_local`(properties)	Update the values of a set of resource properties on this Python object without propagating the updates to 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:

Partition

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:

Port

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.

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 ‘Virtual Storage Resource object’ in the HMC API book.

Raises:

5.16. 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 a Console object.

Attributes:

`console`	The Console object representing the HMC.
`case_insensitive_names`	`bool`: Indicates whether the names of the resources are treated case insensitively.
`class_name`	The resource class name
`name_prop`	The name of the resource property indicating the resource 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.
`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.
`uri`	The canonical URI path of the manager.

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.
`add_resources_local`(resource_obj_list)	Add a resource object to the local auto-updated list of resources.
`auto_update_enabled`()	Return whether Auto-updating is currently enabled for the manager object.
`auto_update_needs_pull`()	Return whether there is a need to pull the resources from the HMC, in the list() method.
`auto_update_trigger_pull`()	Trigger the need to pull the resources from the HMC, in the list() method.
`disable_auto_update`()	Disable Auto-updating for this manager object, if currently enabled.
`dump`()	Dump the resources of this resource manager as a resource definition.
`enable_auto_update`()	Enable Auto-updating for this manager object, if currently disabled.
`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. for a CPC, a `Cpc` object is returned).
`find_by_name`(name)	Find a resource by name and return its Python resource object (e.g. for a CPC, a `Cpc` object is returned).
`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. for CPCs, a list of `Cpc` objects is returned).
`flush`()	Invalidate the Name-URI cache of this manager.
`invalidate_cache`()	Invalidate the Name-URI cache of this manager.
`list_resources_local`()	List the resource objects from the local auto-updated list of resources.
`remove_resource_local`(resource_uri)	Remove the resource object for a resource URI from the local auto-updated list of resources.
`resource_object`(uri_or_oid[, props])	Return a minimalistic Python resource object for this resource class, that is scoped to this manager.

property console

The Console object representing the HMC.

Type:: Console

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.

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, if the filter arguments specify the resource name as a single filter argument with a straight match string (i.e. without regular expressions), an optimized lookup is performed based on a locally maintained name-URI cache.
Otherwise, the HMC List operation is performed with the subset of the provided filter arguments that can be handled on the HMC side and the remaining filter arguments are applied on the client side on the list result.

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:

StorageGroupTemplate

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:

`storage_volume_templates`	Access to the storage volumes in this storage group.
`cpc`	The CPC to which this storage group template is associated.
`ceased_existence`	Indicates that the corresponding object on the HMC no longer exists, if auto-update is enabled for the 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:

`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-updating is currently enabled for the resource object.
`cease_existence_local`()	Update this Python object to indicate that the corresponding HMC object no longer exists.
`disable_auto_update`()	Disable Auto-updating for this resource object, if currently enabled.
`dump`()	Dump this resource with its properties and child resources (recursively) as a resource definition.
`enable_auto_update`()	Enable Auto-updating 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 cached in this Python object, without retrieving them from the HMC.
`get_properties_pulled`(names)	Return a set of resource properties with the values they currently have on 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 the resource does not have a property with that name.
`pull_full_properties`()	Retrieve the full set of resource properties from the HMC and cache them in this Python object.
`pull_properties`(properties)	Retrieve the specified set of resource properties from the HMC and cache them in this Python object.
`update_properties_local`(properties)	Update the values of a set of resource properties on this Python object without propagating the updates to the HMC.

property storage_volume_templates

Access to the storage volumes in this storage group.

Type:: StorageVolumeManager

property cpc

The CPC to which this storage group template is associated.

The returned Cpc has only a minimal set of properties populated.

Type:: Cpc

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 on storage_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.

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 Template Properties’ in the HMC API book.

Raises:

5.17. 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:

storage_volume_templates

Attributes:

`storage_group_template`	`StorageGroupTemplate`: Storage group template defining the scope for this manager.
`case_insensitive_names`	`bool`: Indicates whether the names of the resources are treated case insensitively.
`class_name`	The resource class name
`name_prop`	The name of the resource property indicating the resource 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.
`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.
`uri`	The canonical URI path of the manager.

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.
`add_resources_local`(resource_obj_list)	Add a resource object to the local auto-updated list of resources.
`auto_update_enabled`()	Return whether Auto-updating is currently enabled for the manager object.
`auto_update_needs_pull`()	Return whether there is a need to pull the resources from the HMC, in the list() method.
`auto_update_trigger_pull`()	Trigger the need to pull the resources from the HMC, in the list() method.
`disable_auto_update`()	Disable Auto-updating for this manager object, if currently enabled.
`dump`()	Dump the resources of this resource manager as a resource definition.
`enable_auto_update`()	Enable Auto-updating for this manager object, if currently disabled.
`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. for a CPC, a `Cpc` object is returned).
`find_by_name`(name)	Find a resource by name and return its Python resource object (e.g. for a CPC, a `Cpc` object is returned).
`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. for CPCs, a list of `Cpc` objects is returned).
`flush`()	Invalidate the Name-URI cache of this manager.
`invalidate_cache`()	Invalidate the Name-URI cache of this manager.
`list_resources_local`()	List the resource objects from the local auto-updated list of resources.
`remove_resource_local`(resource_uri)	Remove the resource object for a resource URI from the local auto-updated list of resources.
`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.

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, if the filter arguments specify the resource name as a single filter argument with a straight match string (i.e. without regular expressions), an optimized lookup is performed based on a locally maintained name-URI cache.
Otherwise, the HMC List operation is performed with the subset of the provided filter arguments that can be handled on the HMC side and the remaining filter arguments are applied on the client side on the list result.

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:

StorageVolumeTemplate

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-updating is currently enabled for the resource object.
`cease_existence_local`()	Update this Python object to indicate that the corresponding HMC object no longer exists.
`disable_auto_update`()	Disable Auto-updating for this resource object, if currently enabled.
`dump`()	Dump this resource with its properties and child resources (recursively) as a resource definition.
`enable_auto_update`()	Enable Auto-updating 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 cached in this Python object, without retrieving them from the HMC.
`get_properties_pulled`(names)	Return a set of resource properties with the values they currently have on 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 the resource does not have a property with that name.
`pull_full_properties`()	Retrieve the full set of resource properties from the HMC and cache them in this Python object.
`pull_properties`(properties)	Retrieve the specified set of resource properties from the HMC and cache them in this Python object.
`update_properties_local`(properties)	Update the values of a set of resource properties on this Python object without propagating the updates to the HMC.

Attributes:

`ceased_existence`	Indicates that the corresponding object on the HMC no longer exists, if auto-update is enabled for the 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.

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:

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

capacity_groups

Attributes:

`cpc`	CPC defining the scope for this manager.
`case_insensitive_names`	`bool`: Indicates whether the names of the resources are treated case insensitively.
`class_name`	The resource class name
`name_prop`	The name of the resource property indicating the resource 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.
`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.
`uri`	The canonical URI path of the manager.

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.
`add_resources_local`(resource_obj_list)	Add a resource object to the local auto-updated list of resources.
`auto_update_enabled`()	Return whether Auto-updating is currently enabled for the manager object.
`auto_update_needs_pull`()	Return whether there is a need to pull the resources from the HMC, in the list() method.
`auto_update_trigger_pull`()	Trigger the need to pull the resources from the HMC, in the list() method.
`disable_auto_update`()	Disable Auto-updating for this manager object, if currently enabled.
`dump`()	Dump the resources of this resource manager as a resource definition.
`enable_auto_update`()	Enable Auto-updating for this manager object, if currently disabled.
`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. for a CPC, a `Cpc` object is returned).
`find_by_name`(name)	Find a resource by name and return its Python resource object (e.g. for a CPC, a `Cpc` object is returned).
`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. for CPCs, a list of `Cpc` objects is returned).
`flush`()	Invalidate the Name-URI cache of this manager.
`invalidate_cache`()	Invalidate the Name-URI cache of this manager.
`list_resources_local`()	List the resource objects from the local auto-updated list of resources.
`remove_resource_local`(resource_uri)	Remove the resource object for a resource URI from the local auto-updated list of resources.
`resource_object`(uri_or_oid[, props])	Return a minimalistic Python resource object for this resource class, that is scoped to this manager.

property cpc

CPC defining the scope for this manager.

Type:: Cpc

list(full_properties=False, filter_args=None)[source]

List the Capacity Groups in this CPC.

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, if the filter arguments specify the resource name as a single filter argument with a straight match string (i.e. without regular expressions), an optimized lookup is performed based on a locally maintained name-URI cache.
Otherwise, the HMC List operation is performed with the subset of the provided filter arguments that can be handled on the HMC side and the remaining filter arguments are applied on the client side on the list result.

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:

CapacityGroup

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-updating is currently enabled for the resource object.
`cease_existence_local`()	Update this Python object to indicate that the corresponding HMC object no longer exists.
`disable_auto_update`()	Disable Auto-updating for this resource object, if currently enabled.
`dump`()	Dump this resource with its properties and child resources (recursively) as a resource definition.
`enable_auto_update`()	Enable Auto-updating 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 cached in this Python object, without retrieving them from the HMC.
`get_properties_pulled`(names)	Return a set of resource properties with the values they currently have on 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 the resource does not have a property with that name.
`pull_full_properties`()	Retrieve the full set of resource properties from the HMC and cache them in this Python object.
`pull_properties`(properties)	Retrieve the specified set of resource properties from the HMC and cache them in this Python object.
`update_properties_local`(properties)	Update the values of a set of resource properties on this Python object without propagating the updates to the HMC.

Attributes:

`ceased_existence`	Indicates that the corresponding object on the HMC no longer exists, if auto-update is enabled for the 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.

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.

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 ‘Capacity Group element object’ in the HMC API book.

Raises:

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:

5.19. 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:

zhmcclient.Client.consoles

Attributes:

`client`	`Client`: The client defining the scope for this manager.
`console`	`Console`: The Console representing the HMC this client is connected to.
`case_insensitive_names`	`bool`: Indicates whether the names of the resources are treated case insensitively.
`class_name`	The resource class name
`name_prop`	The name of the resource property indicating the resource 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.
`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.
`uri`	The canonical URI path of the manager.

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.
`add_resources_local`(resource_obj_list)	Add a resource object to the local auto-updated list of resources.
`auto_update_enabled`()	Return whether Auto-updating is currently enabled for the manager object.
`auto_update_needs_pull`()	Return whether there is a need to pull the resources from the HMC, in the list() method.
`auto_update_trigger_pull`()	Trigger the need to pull the resources from the HMC, in the list() method.
`disable_auto_update`()	Disable Auto-updating for this manager object, if currently enabled.
`dump`()	Dump the resources of this resource manager as a resource definition.
`enable_auto_update`()	Enable Auto-updating for this manager object, if currently disabled.
`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. for a CPC, a `Cpc` object is returned).
`find_by_name`(name)	Find a resource by name and return its Python resource object (e.g. for a CPC, a `Cpc` object is returned).
`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. for CPCs, a list of `Cpc` objects is returned).
`flush`()	Invalidate the Name-URI cache of this manager.
`invalidate_cache`()	Invalidate the Name-URI cache of this manager.
`list_resources_local`()	List the resource objects from the local auto-updated list of resources.
`remove_resource_local`(resource_uri)	Remove the resource object for a resource URI from the local auto-updated list of resources.
`resource_object`(uri_or_oid[, props])	Return a minimalistic Python resource object for this resource class, that is scoped to this manager.

property client: Client: The client defining the scope for 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() or prop() 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 (one) Console representing the HMC this client is connected to.

Any provided filter argument will be ignored; the filter_args parameter exists only for consistency with other list() methods.

The listing of resources is handled by constructing a singleton object that represents the HMC of the current session.

Authorization requirements:

None

Parameters:

full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only a short set consisting of ‘object-uri’.
filter_args (dict) – This parameter exists for consistency with other list() methods and will be ignored.

Returns:

A list of Console objects, containing the one Console representing the HMC this client is connected to.

Raises:

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:

`storage_groups`	`StorageGroupManager`: Manager object for the Storage Groups in scope of this Console.
`storage_group_templates`	`StorageGroupTemplateManager`: Manager object for the Storage Group Templates in scope of this Console.
`users`	Access to the Users in this Console.
`user_roles`	Access to the User Roles in this Console.
`user_patterns`	Access to the User Patterns in this Console.
`password_rules`	Access to the Password Rules in this Console.
`tasks`	Access to the Tasks in this Console.
`ldap_server_definitions`	Access to the LDAP Server Definitions in this Console.
`unmanaged_cpcs`	Access to the unmanaged CPCs in this Console.
`groups`	Access to user-defined Groups in this Console.
`certificates`	Access to the Certificates in this HMC.
`ceased_existence`	Indicates that the corresponding object on the HMC no longer exists, if auto-update is enabled for the 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:

`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.
`make_primary`()	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.
`list_permitted_adapters`([full_properties, ...])	List the permitted adapters of all CPCs managed by this HMC.
`list_api_features`([name])	Returns information about the Web Services API features (introduced with Web Services version 4.10) available on this console, see Feature enablement.
`single_step_install`([bundle_level, ...])	Upgrades the firmware on this HMC to a new bundle level.
`dump`()	Dump this Console resource with its properties and child resources (recursively) as a resource definition.
`__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-updating is currently enabled for the resource object.
`cease_existence_local`()	Update this Python object to indicate that the corresponding HMC object no longer exists.
`disable_auto_update`()	Disable Auto-updating for this resource object, if currently enabled.
`enable_auto_update`()	Enable Auto-updating 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 cached in this Python object, without retrieving them from the HMC.
`get_properties_pulled`(names)	Return a set of resource properties with the values they currently have on 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 the resource does not have a property with that name.
`pull_full_properties`()	Retrieve the full set of resource properties from the HMC and cache them in this Python object.
`pull_properties`(properties)	Retrieve the specified set of resource properties from the HMC and cache them in this Python object.
`update_properties_local`(properties)	Update the values of a set of resource properties on this Python object without propagating the updates to 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 users

Access to the Users in this Console.

Type:: UserManager

property user_roles

Access to the User Roles in this Console.

Type:: UserRoleManager

property user_patterns

Access to the User Patterns in this Console.

Type:: UserPatternManager

property password_rules

Access to the Password Rules in this Console.

Type:: PasswordRuleManager

property tasks

Access to the Tasks in this Console.

Type:: TaskManager

property ldap_server_definitions

Access to the LDAP Server Definitions in this Console.

Type:: LdapServerDefinitionManager

property unmanaged_cpcs

Access to the unmanaged CPCs in this Console.

Type:: UnmanagedCpcManager

property groups

Access to user-defined Groups in this Console.

Type:: GroupManager

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:

HTTPError –
ParseError –
AuthError –
ConnectionError –
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:

json object

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:

json object

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, additional_properties=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.

The partitions in the result will have the following partition properties:

name (string): Name of the partition.
object-uri (string): Object URI of the partition.
type (string): Type of the partition (i.e. “linux”, “ssc”, “zvm”).
status (string): Status of the partition. See the data model of the Partition object in the HMC API book for values.
has-unacceptable-status (bool): Whether the status is unacceptable, according to the values in the ‘acceptable-status’ property.

and the following properties from their parent CPC:

cpc-name (string): Name of the parent CPC of the partition.
cpc-object-uri (string): Object URI of the parent CPC of the partition.
se-version (string): SE version of the parent CPC of the partition, as M.N.U string. Note that this property is returned only on newer HMC 2.16 versions (HMC API version 4.10 or higher).

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.
additional_properties (list of string) –
List of property names that are to be returned in addition to the default properties.

This parameter requires API feature “dpm-hipersockets-partition-link-management” or “dpm-ctc-partition-link-management”.

Returns:

A list of Partition objects.

Raises:

list_permitted_lpars(full_properties=False, filter_args=None, additional_properties=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.

The LPARs in the result will have the following LPAR properties:

name (string): Name of the LPAR.
object-uri (string): Object URI of the LPAR.
activation-mode (string): Activation mode of the LPAR. See the data model of the Logical Partition object in the HMC API book for values.
status (string): Status of the LPAR. See the data model of the Logical Partition object in the HMC API book for values.
has-unacceptable-status (bool): Whether the status is unacceptable, according to the values in the ‘acceptable-status’ property.

and the following properties from their parent CPC:

cpc-name (string): Name of the parent CPC of the LPAR.
cpc-object-uri (string): Object URI of the parent CPC of the LPAR.
se-version (string): SE version of the parent CPC of the LPAR, as M.N.U string. Note that this property is returned only on newer HMC 2.16 versions (HMC API version 4.10 or higher).

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.
additional_properties (list of string) –
List of property names that are to be returned in addition to the default properties.

Note: This parameter is handled by the HMC starting with HMC API version 4.10 (HMC 2.16 GA 1.5); with older HMC API versions it is handled by zhmcclient.

Returns:

A list of Lpar objects.

Raises:

list_permitted_adapters(full_properties=False, filter_args=None, additional_properties=None)[source]

List the permitted adapters of all CPCs managed by this HMC.

The result will include all adapters of any DPM CPCs and z15 or later classic-mode CPCs that are managed by the targeted HMC and to which the user has object-access permission.

If ‘additional_properties’ is not used, requires HMC API version 4.1 or later (= HMC version 2.16.0 GA-level) and otherwise raises HTTPError(404.4).

If ‘additional_properties’ is used, requires HMC API version 4.10 or later (= HMC version 2.16.0 plus some post-GA code level) and otherwise raises HTTPError(404.4).

The adapters in the result can be additionally limited by specifying filter arguments.

Authorization requirements:

Object permission to the adapter objects included in the result.

Parameters:

full_properties (bool) – Controls whether the full set of resource properties for the returned Adapter objects should be retrieved, vs. only a short set.
filter_args (dict) –
Filter arguments for limiting the adapters 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 adapters whose name match the specified regular expression.
- adapter-id (string): Limits the result to adapters with a matching “adapter-id” property value (i.e. PCHID).
- adapter-family (string): Limits the result to adapters with a matching “adapter-family” property value (e.g. “hipersockets”).
- type (string): Limits the result to adapters with a matching “type” property value (e.g. “hipersockets”).
- status (string): Limits the result to adapters with a matching “status” property value.
- firmware-update-pending (bool): Limits the result to adapters with a matching firmware-update-pending state.
- cpc-name (string): Limits the result to adapters whose CPC has a name that matches the specified regular expression.
- dpm-enabled (bool): Limits the result to adapters whose CPC has a matching “dpm-enabled” property.
Any other valid property of adapters is supported by client-side filtering:
- <property-name>: Any other property of adapters.
additional_properties (list of string) – List of property names that are to be returned in addition to the default properties.

Returns:

A list of Adapter objects.

If no additional or full properties are specified, the returned adapters will have the following properties:

object-uri, name, adapter-id, adapter-family, type, status,
firmware-update-pending (if CPC >=2.16 and LI_1580_CRYPTO_AUTO_TOGGLE feature is enabled)

and the following properties for their parent CPC:

cpc-name (CPC property ‘name’)
cpc-object-uri (CPC property ‘object-uri’)
se-version (CPC property ‘se-version’)
dpm-enabled (CPC property ‘dpm-enabled’)

Raises:

list_api_features(name=None)[source]

Returns information about the Web Services API features (introduced with Web Services version 4.10) available on this console, see Feature enablement.

Parameters:: name – A regular expression used to limit returned objects to those that have a matching name field.

Authorization requirements:

None

Returns:: The list of API features that are available on this client. For API versions prior to 4.10, an empty list is returned.
Return type:: list of strings

property certificates

Access to the Certificates in this HMC.

Type:: CertificateManager

single_step_install(bundle_level=None, backup_location_type='usb', accept_firmware=True, ftp_host=None, ftp_protocol=None, ftp_user=None, ftp_password=None, ftp_directory=None, wait_for_completion=True, operation_timeout=None)[source]

Upgrades the firmware on this HMC to a new bundle level.

This is done by performing the “Console Single Step Install” operation which performs the following steps:

If accept_firmware is True, the firmware currently installed on the this HMC is accepted. Note that once firmware is accepted, it cannot be removed.
A backup of the this HMC is performed to the specified backup device.
The new firmware identified by the bundle-level field is retrieved from the IBM support site or from an FTP server, and installed.
The newly installed firmware is activated, which includes rebooting this HMC.

Note that it is not possible to downgrade the HMC firmware with this operation.

For HMCs that run on an HMA that also hosts an SE (e.g. z16 and higher), the HMC firmware can only be upgraded if the HMA hosts an alternate SE.

Authorization requirements:

Task permission to the “Single Step Console Internal Code” task.

Parameters:

bundle_level (string) – Name of the bundle to be installed on the HMC (e.g. ‘H71’). If None, all locally available code changes, or in case of retrieving code changes from an FTP server, all code changes on the FTP server, will be installed.
backup_location_type (string) –
Type of backup location for the HMC backup that is performed:
- ”ftp”: The FTP server that was used for the last console backup as defined on the “Configure Backup Settings” user interface task in the HMC GUI.
- ”usb”: The USB storage device mounted to the HMC.
accept_firmware (bool) – Accept the previous bundle level before installing the new level.
ftp_host (string) – The hostname for the FTP server from which the firmware will be retrieved, or None to retrieve it from the IBM support site.
ftp_protocol (string) – The protocol to connect to the FTP server, if the firmware will be retrieved from an FTP server, or None. Valid values are: “ftp”, “ftps”, “sftp”.
ftp_user (string) – The username for the FTP server login, if the firmware will be retrieved from an FTP server, or None.
ftp_password (string) – The password for the FTP server login, if the firmware will be retrieved from an FTP server, or None.
ftp_directory (string) – The path name of the directory on the FTP server with the firmware files, if the firmware will be retrieved from an FTP server, or None.
wait_for_completion (bool) –
Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation including any HMC restarts, as follows:
- If True, this method will wait for completion of the asynchronous job performing the operation including any HMC restarts.
- 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 including any HMC restarts. 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. The Job object will be valid across any HMC restarts that occur during the upgrade operation.

This job supports cancellation. Note there are only a few interruption points in the firmware install process, so it may be some time before the job is canceled, and after some point, will continue on to completion. The job status and reason codes will indicate whether the job was canceled or ran to completion. If the job is successfully canceled, any steps that were successfully completed will not be rolled back.

Return type:

None or Job

Raises:

HTTPError –
ParseError –
AuthError –
ConnectionError –
OperationTimeout – The timeout expired while waiting for completion of the operation.

dump()[source]

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

The returned resource definition has the following format:

{
    # Resource properties:
    "properties": {...},

    # Child resources:
    "users": [...],
    "user_roles": [...],
    "user_patterns": [...],
    "password_rules": [...],
    "tasks": [...],
    "ldap_server_definitions": [...],
    "unmanaged_cpcs": [...],
    "storage_groups": [...],
}

Returns:: Resource definition of this resource.
Return type:: dict

5.20. 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:

zhmcclient.Console.users

Attributes:

`console`	Console defining the scope for this manager.
`case_insensitive_names`	`bool`: Indicates whether the names of the resources are treated case insensitively.
`class_name`	The resource class name
`name_prop`	The name of the resource property indicating the resource 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.
`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.
`uri`	The canonical URI path of the manager.

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.
`add_resources_local`(resource_obj_list)	Add a resource object to the local auto-updated list of resources.
`auto_update_enabled`()	Return whether Auto-updating is currently enabled for the manager object.
`auto_update_needs_pull`()	Return whether there is a need to pull the resources from the HMC, in the list() method.
`auto_update_trigger_pull`()	Trigger the need to pull the resources from the HMC, in the list() method.
`disable_auto_update`()	Disable Auto-updating for this manager object, if currently enabled.
`dump`()	Dump the resources of this resource manager as a resource definition.
`enable_auto_update`()	Enable Auto-updating for this manager object, if currently disabled.
`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. for a CPC, a `Cpc` object is returned).
`find_by_name`(name)	Find a resource by name and return its Python resource object (e.g. for a CPC, a `Cpc` object is returned).
`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. for CPCs, a list of `Cpc` objects is returned).
`flush`()	Invalidate the Name-URI cache of this manager.
`invalidate_cache`()	Invalidate the Name-URI cache of this manager.
`list_resources_local`()	List the resource objects from the local auto-updated list of resources.
`remove_resource_local`(resource_uri)	Remove the resource object for a resource URI from the local auto-updated list of resources.
`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 defining the scope for this manager.

Type:: Console

list(full_properties=False, filter_args=None)[source]

List the User resources representing the users defined in this HMC.

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, if the filter arguments specify the resource name as a single filter argument with a straight match string (i.e. without regular expressions), an optimized lookup is performed based on a locally maintained name-URI cache.
Otherwise, the HMC List operation is performed with the subset of the provided filter arguments that can be handled on the HMC side and the remaining filter arguments are applied on the client side on the list result.

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:

User

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-updating is currently enabled for the resource object.
`cease_existence_local`()	Update this Python object to indicate that the corresponding HMC object no longer exists.
`disable_auto_update`()	Disable Auto-updating for this resource object, if currently enabled.
`dump`()	Dump this resource with its properties and child resources (recursively) as a resource definition.
`enable_auto_update`()	Enable Auto-updating 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 cached in this Python object, without retrieving them from the HMC.
`get_properties_pulled`(names)	Return a set of resource properties with the values they currently have on 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 the resource does not have a property with that name.
`pull_full_properties`()	Retrieve the full set of resource properties from the HMC and cache them in this Python object.
`pull_properties`(properties)	Retrieve the specified set of resource properties from the HMC and cache them in this Python object.
`update_properties_local`(properties)	Update the values of a set of resource properties on this Python object without propagating the updates to the HMC.

Attributes:

`ceased_existence`	Indicates that the corresponding object on the HMC no longer exists, if auto-update is enabled for the 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.

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.

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 ‘User object’ in the HMC API book.

Raises:

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:

5.21. 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:

zhmcclient.Console.user_roles

Attributes:

`console`	Console defining the scope for this manager.
`case_insensitive_names`	`bool`: Indicates whether the names of the resources are treated case insensitively.
`class_name`	The resource class name
`name_prop`	The name of the resource property indicating the resource 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.
`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.
`uri`	The canonical URI path of the manager.

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.
`add_resources_local`(resource_obj_list)	Add a resource object to the local auto-updated list of resources.
`auto_update_enabled`()	Return whether Auto-updating is currently enabled for the manager object.
`auto_update_needs_pull`()	Return whether there is a need to pull the resources from the HMC, in the list() method.
`auto_update_trigger_pull`()	Trigger the need to pull the resources from the HMC, in the list() method.
`disable_auto_update`()	Disable Auto-updating for this manager object, if currently enabled.
`dump`()	Dump the resources of this resource manager as a resource definition.
`enable_auto_update`()	Enable Auto-updating for this manager object, if currently disabled.
`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. for a CPC, a `Cpc` object is returned).
`find_by_name`(name)	Find a resource by name and return its Python resource object (e.g. for a CPC, a `Cpc` object is returned).
`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. for CPCs, a list of `Cpc` objects is returned).
`flush`()	Invalidate the Name-URI cache of this manager.
`invalidate_cache`()	Invalidate the Name-URI cache of this manager.
`list_resources_local`()	List the resource objects from the local auto-updated list of resources.
`remove_resource_local`(resource_uri)	Remove the resource object for a resource URI from the local auto-updated list of resources.
`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 defining the scope for this manager.

Type:: Console

list(full_properties=False, filter_args=None)[source]

List the User Role resources representing the user roles defined in this HMC.

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, if the filter arguments specify the resource name as a single filter argument with a straight match string (i.e. without regular expressions), an optimized lookup is performed based on a locally maintained name-URI cache.
Otherwise, the HMC List operation is performed with the subset of the provided filter arguments that can be handled on the HMC side and the remaining filter arguments are applied on the client side on the list result.

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:

UserRole

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-updating is currently enabled for the resource object.
`cease_existence_local`()	Update this Python object to indicate that the corresponding HMC object no longer exists.
`disable_auto_update`()	Disable Auto-updating for this resource object, if currently enabled.
`dump`()	Dump this resource with its properties and child resources (recursively) as a resource definition.
`enable_auto_update`()	Enable Auto-updating 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 cached in this Python object, without retrieving them from the HMC.
`get_properties_pulled`(names)	Return a set of resource properties with the values they currently have on 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 the resource does not have a property with that name.
`pull_full_properties`()	Retrieve the full set of resource properties from the HMC and cache them in this Python object.
`pull_properties`(properties)	Retrieve the specified set of resource properties from the HMC and cache them in this Python object.
`update_properties_local`(properties)	Update the values of a set of resource properties on this Python object without propagating the updates to the HMC.

Attributes:

`ceased_existence`	Indicates that the corresponding object on the HMC no longer exists, if auto-update is enabled for the 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.

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.

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 ‘User Role object’ in the HMC API book.

Raises:

add_permission(permitted_object, include_members=None, view_only=None)[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.

If None, this parameter will be ignored. It should only be specified when the permitted object is a Group resource.
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.

If None, this parameter will be ignored. It should only be specified when the permitted object is a Task resource.

Raises:

remove_permission(permitted_object, include_members=None, view_only=None)[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.

If None, this parameter will be ignored. It should only be specified when the permitted object is a Group resource.
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.

If None, this parameter will be ignored. It should only be specified when the permitted object is a Task resource.

Raises:

5.22. 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:

zhmcclient.Console.user_patterns

Attributes:

`console`	Console defining the scope for this manager.
`case_insensitive_names`	`bool`: Indicates whether the names of the resources are treated case insensitively.
`class_name`	The resource class name
`name_prop`	The name of the resource property indicating the resource 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.
`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.
`uri`	The canonical URI path of the manager.

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.
`add_resources_local`(resource_obj_list)	Add a resource object to the local auto-updated list of resources.
`auto_update_enabled`()	Return whether Auto-updating is currently enabled for the manager object.
`auto_update_needs_pull`()	Return whether there is a need to pull the resources from the HMC, in the list() method.
`auto_update_trigger_pull`()	Trigger the need to pull the resources from the HMC, in the list() method.
`disable_auto_update`()	Disable Auto-updating for this manager object, if currently enabled.
`dump`()	Dump the resources of this resource manager as a resource definition.
`enable_auto_update`()	Enable Auto-updating for this manager object, if currently disabled.
`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. for a CPC, a `Cpc` object is returned).
`find_by_name`(name)	Find a resource by name and return its Python resource object (e.g. for a CPC, a `Cpc` object is returned).
`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. for CPCs, a list of `Cpc` objects is returned).
`flush`()	Invalidate the Name-URI cache of this manager.
`invalidate_cache`()	Invalidate the Name-URI cache of this manager.
`list_resources_local`()	List the resource objects from the local auto-updated list of resources.
`remove_resource_local`(resource_uri)	Remove the resource object for a resource URI from the local auto-updated list of resources.
`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 defining the scope for this manager.

Type:: Console

list(full_properties=False, filter_args=None)[source]

List the User Pattern resources representing the user patterns defined in this HMC.

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, if the filter arguments specify the resource name as a single filter argument with a straight match string (i.e. without regular expressions), an optimized lookup is performed based on a locally maintained name-URI cache.
Otherwise, the HMC List operation is performed with the subset of the provided filter arguments that can be handled on the HMC side and the remaining filter arguments are applied on the client side on the list result.

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:

UserPattern

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-updating is currently enabled for the resource object.
`cease_existence_local`()	Update this Python object to indicate that the corresponding HMC object no longer exists.
`disable_auto_update`()	Disable Auto-updating for this resource object, if currently enabled.
`dump`()	Dump this resource with its properties and child resources (recursively) as a resource definition.
`enable_auto_update`()	Enable Auto-updating 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 cached in this Python object, without retrieving them from the HMC.
`get_properties_pulled`(names)	Return a set of resource properties with the values they currently have on 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 the resource does not have a property with that name.
`pull_full_properties`()	Retrieve the full set of resource properties from the HMC and cache them in this Python object.
`pull_properties`(properties)	Retrieve the specified set of resource properties from the HMC and cache them in this Python object.
`update_properties_local`(properties)	Update the values of a set of resource properties on this Python object without propagating the updates to the HMC.

Attributes:

`ceased_existence`	Indicates that the corresponding object on the HMC no longer exists, if auto-update is enabled for the 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.

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.

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 ‘User Pattern object’ in the HMC API book.

Raises:

5.23. 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:

zhmcclient.Console.password_rules

Attributes:

`console`	Console defining the scope for this manager.
`case_insensitive_names`	`bool`: Indicates whether the names of the resources are treated case insensitively.
`class_name`	The resource class name
`name_prop`	The name of the resource property indicating the resource 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.
`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.
`uri`	The canonical URI path of the manager.

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.
`add_resources_local`(resource_obj_list)	Add a resource object to the local auto-updated list of resources.
`auto_update_enabled`()	Return whether Auto-updating is currently enabled for the manager object.
`auto_update_needs_pull`()	Return whether there is a need to pull the resources from the HMC, in the list() method.
`auto_update_trigger_pull`()	Trigger the need to pull the resources from the HMC, in the list() method.
`disable_auto_update`()	Disable Auto-updating for this manager object, if currently enabled.
`dump`()	Dump the resources of this resource manager as a resource definition.
`enable_auto_update`()	Enable Auto-updating for this manager object, if currently disabled.
`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. for a CPC, a `Cpc` object is returned).
`find_by_name`(name)	Find a resource by name and return its Python resource object (e.g. for a CPC, a `Cpc` object is returned).
`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. for CPCs, a list of `Cpc` objects is returned).
`flush`()	Invalidate the Name-URI cache of this manager.
`invalidate_cache`()	Invalidate the Name-URI cache of this manager.
`list_resources_local`()	List the resource objects from the local auto-updated list of resources.
`remove_resource_local`(resource_uri)	Remove the resource object for a resource URI from the local auto-updated list of resources.
`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 defining the scope for this manager.

Type:: Console

list(full_properties=False, filter_args=None)[source]

List the Password Rule resources representing the password rules defined in this HMC.

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, if the filter arguments specify the resource name as a single filter argument with a straight match string (i.e. without regular expressions), an optimized lookup is performed based on a locally maintained name-URI cache.
Otherwise, the HMC List operation is performed with the subset of the provided filter arguments that can be handled on the HMC side and the remaining filter arguments are applied on the client side on the list result.

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:

PasswordRule

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-updating is currently enabled for the resource object.
`cease_existence_local`()	Update this Python object to indicate that the corresponding HMC object no longer exists.
`disable_auto_update`()	Disable Auto-updating for this resource object, if currently enabled.
`dump`()	Dump this resource with its properties and child resources (recursively) as a resource definition.
`enable_auto_update`()	Enable Auto-updating 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 cached in this Python object, without retrieving them from the HMC.
`get_properties_pulled`(names)	Return a set of resource properties with the values they currently have on 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 the resource does not have a property with that name.
`pull_full_properties`()	Retrieve the full set of resource properties from the HMC and cache them in this Python object.
`pull_properties`(properties)	Retrieve the specified set of resource properties from the HMC and cache them in this Python object.
`update_properties_local`(properties)	Update the values of a set of resource properties on this Python object without propagating the updates to the HMC.

Attributes:

`ceased_existence`	Indicates that the corresponding object on the HMC no longer exists, if auto-update is enabled for the 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.

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.

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 ‘Password Rule object’ in the HMC API book.

Raises:

5.24. 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:

zhmcclient.Console.tasks

Attributes:

`console`	Console defining the scope for this manager.
`case_insensitive_names`	`bool`: Indicates whether the names of the resources are treated case insensitively.
`class_name`	The resource class name
`name_prop`	The name of the resource property indicating the resource 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.
`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.
`uri`	The canonical URI path of the manager.

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.
`add_resources_local`(resource_obj_list)	Add a resource object to the local auto-updated list of resources.
`auto_update_enabled`()	Return whether Auto-updating is currently enabled for the manager object.
`auto_update_needs_pull`()	Return whether there is a need to pull the resources from the HMC, in the list() method.
`auto_update_trigger_pull`()	Trigger the need to pull the resources from the HMC, in the list() method.
`disable_auto_update`()	Disable Auto-updating for this manager object, if currently enabled.
`dump`()	Dump the resources of this resource manager as a resource definition.
`enable_auto_update`()	Enable Auto-updating for this manager object, if currently disabled.
`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. for a CPC, a `Cpc` object is returned).
`find_by_name`(name)	Find a resource by name and return its Python resource object (e.g. for a CPC, a `Cpc` object is returned).
`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. for CPCs, a list of `Cpc` objects is returned).
`flush`()	Invalidate the Name-URI cache of this manager.
`invalidate_cache`()	Invalidate the Name-URI cache of this manager.
`list_resources_local`()	List the resource objects from the local auto-updated list of resources.
`remove_resource_local`(resource_uri)	Remove the resource object for a resource URI from the local auto-updated list of resources.
`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 defining the scope for this manager.

Type:: Console

list(full_properties=False, filter_args=None)[source]

List the Task resources representing the tasks defined in this HMC.

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, if the filter arguments specify the resource name as a single filter argument with a straight match string (i.e. without regular expressions), an optimized lookup is performed based on a locally maintained name-URI cache.
Otherwise, the HMC List operation is performed with the subset of the provided filter arguments that can be handled on the HMC side and the remaining filter arguments are applied on the client side on the list result.

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-updating is currently enabled for the resource object.
`cease_existence_local`()	Update this Python object to indicate that the corresponding HMC object no longer exists.
`disable_auto_update`()	Disable Auto-updating for this resource object, if currently enabled.
`dump`()	Dump this resource with its properties and child resources (recursively) as a resource definition.
`enable_auto_update`()	Enable Auto-updating 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 cached in this Python object, without retrieving them from the HMC.
`get_properties_pulled`(names)	Return a set of resource properties with the values they currently have on 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 the resource does not have a property with that name.
`pull_full_properties`()	Retrieve the full set of resource properties from the HMC and cache them in this Python object.
`pull_properties`(properties)	Retrieve the specified set of resource properties from the HMC and cache them in this Python object.
`update_properties_local`(properties)	Update the values of a set of resource properties on this Python object without propagating the updates to the HMC.

Attributes:

`ceased_existence`	Indicates that the corresponding object on the HMC no longer exists, if auto-update is enabled for the 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.

5.25. 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:

zhmcclient.Console.ldap_server_definitions

Attributes:

`console`	Console defining the scope for this manager.
`case_insensitive_names`	`bool`: Indicates whether the names of the resources are treated case insensitively.
`class_name`	The resource class name
`name_prop`	The name of the resource property indicating the resource 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.
`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.
`uri`	The canonical URI path of the manager.

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.
`add_resources_local`(resource_obj_list)	Add a resource object to the local auto-updated list of resources.
`auto_update_enabled`()	Return whether Auto-updating is currently enabled for the manager object.
`auto_update_needs_pull`()	Return whether there is a need to pull the resources from the HMC, in the list() method.
`auto_update_trigger_pull`()	Trigger the need to pull the resources from the HMC, in the list() method.
`disable_auto_update`()	Disable Auto-updating for this manager object, if currently enabled.
`dump`()	Dump the resources of this resource manager as a resource definition.
`enable_auto_update`()	Enable Auto-updating for this manager object, if currently disabled.
`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. for a CPC, a `Cpc` object is returned).
`find_by_name`(name)	Find a resource by name and return its Python resource object (e.g. for a CPC, a `Cpc` object is returned).
`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. for CPCs, a list of `Cpc` objects is returned).
`flush`()	Invalidate the Name-URI cache of this manager.
`invalidate_cache`()	Invalidate the Name-URI cache of this manager.
`list_resources_local`()	List the resource objects from the local auto-updated list of resources.
`remove_resource_local`(resource_uri)	Remove the resource object for a resource URI from the local auto-updated list of resources.
`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 defining the scope for this manager.

Type:: Console

list(full_properties=False, filter_args=None)[source]

List the LDAP Server Definition resources representing the definitions of LDAp servers in this HMC.

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, if the filter arguments specify the resource name as a single filter argument with a straight match string (i.e. without regular expressions), an optimized lookup is performed based on a locally maintained name-URI cache.
Otherwise, the HMC List operation is performed with the subset of the provided filter arguments that can be handled on the HMC side and the remaining filter arguments are applied on the client side on the list result.

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:

LdapServerDefinition

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-updating is currently enabled for the resource object.
`cease_existence_local`()	Update this Python object to indicate that the corresponding HMC object no longer exists.
`disable_auto_update`()	Disable Auto-updating for this resource object, if currently enabled.
`dump`()	Dump this resource with its properties and child resources (recursively) as a resource definition.
`enable_auto_update`()	Enable Auto-updating 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 cached in this Python object, without retrieving them from the HMC.
`get_properties_pulled`(names)	Return a set of resource properties with the values they currently have on 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 the resource does not have a property with that name.
`pull_full_properties`()	Retrieve the full set of resource properties from the HMC and cache them in this Python object.
`pull_properties`(properties)	Retrieve the specified set of resource properties from the HMC and cache them in this Python object.
`update_properties_local`(properties)	Update the values of a set of resource properties on this Python object without propagating the updates to the HMC.

Attributes:

`ceased_existence`	Indicates that the corresponding object on the HMC no longer exists, if auto-update is enabled for the 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.

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.

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 ‘LDAP Server Definition object’ in the HMC API book.

Raises:

5.26. Certificates

A Certificate represents an X.509 certificate.

Certificates are top level resources, but at this point, only certificates of type “secure-boot” are supported. Such certificates are always associated to a specific CPC. They can only be used if the API feature “secure-boot-with-certificates” is available on both, HMC and CPC.

They can be assigned to one or more LPAR, Partition, or Image Activation Profile to be used during the load/start of the corresponding entities when doing a “secure boot” load for an LPAR, respectively a Partition start.

class zhmcclient.CertificateManager(console)[source]

Manager providing access to the Certificates of an 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:

certificates of a Console object.

Attributes:

`console`	The Console object representing the HMC.
`case_insensitive_names`	`bool`: Indicates whether the names of the resources are treated case insensitively.
`class_name`	The resource class name
`name_prop`	The name of the resource property indicating the resource 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.
`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.
`uri`	The canonical URI path of the manager.

Methods:

`list`([full_properties, filter_args, ...])	List the certificates defined in the HMC.
`import_certificate`(cpc, properties)	Imports a certificate to a CPC.
`__repr__`()	Return a string with the state of this manager object, for debug purposes.
`add_resources_local`(resource_obj_list)	Add a resource object to the local auto-updated list of resources.
`auto_update_enabled`()	Return whether Auto-updating is currently enabled for the manager object.
`auto_update_needs_pull`()	Return whether there is a need to pull the resources from the HMC, in the list() method.
`auto_update_trigger_pull`()	Trigger the need to pull the resources from the HMC, in the list() method.
`disable_auto_update`()	Disable Auto-updating for this manager object, if currently enabled.
`dump`()	Dump the resources of this resource manager as a resource definition.
`enable_auto_update`()	Enable Auto-updating for this manager object, if currently disabled.
`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. for a CPC, a `Cpc` object is returned).
`find_by_name`(name)	Find a resource by name and return its Python resource object (e.g. for a CPC, a `Cpc` object is returned).
`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. for CPCs, a list of `Cpc` objects is returned).
`flush`()	Invalidate the Name-URI cache of this manager.
`invalidate_cache`()	Invalidate the Name-URI cache of this manager.
`list_resources_local`()	List the resource objects from the local auto-updated list of resources.
`remove_resource_local`(resource_uri)	Remove the resource object for a resource URI from the local auto-updated list of resources.
`resource_object`(uri_or_oid[, props])	Return a minimalistic Python resource object for this resource class, that is scoped to this manager.

property console

The Console object representing the HMC.

Type:: Console

list(full_properties=False, filter_args=None, additional_properties=None)[source]

List the certificates defined in the HMC.

Authorization requirements:

Object-access permission to any Certificate 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.
additional_properties (list of string) – List of property names that are to be returned in addition to the default properties.

Returns:

A list of Certificate objects.

Raises:

import_certificate(cpc, properties)[source]

Imports a certificate to a CPC.

Authorization requirements:

Object-access permission to the given CPC.
Task permission for the “Import Secure Boot Certificates” task.

Parameters:

cpc (Cpc) – the CPC the certificate will be
to. (imported) –
properties (dict) – Initial property values. Allowable properties are defined in section ‘Request body contents’ in section ‘Import CPC Certificate’ in the HMC API book.

Returns:

The resource object for the new Certificate. The object will have its ‘object-uri’ property set as returned by the HMC, and will also have the input properties set.

Return type:

Certificate

Raises:

class zhmcclient.Certificate(manager, uri, name=None, properties=None)[source]

Representation of a Certificate.

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, CertificateManager).

Attributes:

`cpc`	The CPC to which this storage group is associated.
`ceased_existence`	Indicates that the corresponding object on the HMC no longer exists, if auto-update is enabled for the 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:

`delete`()	Delete this Certificate.
`update_properties`(properties)	Update writeable properties of this Certificate.
`get_encoded`()	Gets the Base64 encoded string and the file format of this certificate.
`dump`()	Dump this Certificate resource with its properties as a resource definition.
`__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-updating is currently enabled for the resource object.
`cease_existence_local`()	Update this Python object to indicate that the corresponding HMC object no longer exists.
`disable_auto_update`()	Disable Auto-updating for this resource object, if currently enabled.
`enable_auto_update`()	Enable Auto-updating 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 cached in this Python object, without retrieving them from the HMC.
`get_properties_pulled`(names)	Return a set of resource properties with the values they currently have on 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 the resource does not have a property with that name.
`pull_full_properties`()	Retrieve the full set of resource properties from the HMC and cache them in this Python object.
`pull_properties`(properties)	Retrieve the specified set of resource properties from the HMC and cache them in this Python object.
`update_properties_local`(properties)	Update the values of a set of resource properties on this Python object without propagating the updates to the HMC.

property cpc

The CPC to which this storage group is associated.

The returned Cpc has only a minimal set of properties populated.

Type:: Cpc

delete()[source]

Delete this Certificate.

Authorization requirements:

Object-access permission to this Certificate.
Task permission to the “Import Secure Boot Certificates” task.

Raises:

update_properties(properties)[source]

Update writeable properties of this Certificate.

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

Authorization requirements:

Object-access permission to this Certificate.
Task permission to the “Certificate Details” 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 ‘Certificate object’ in the HMC API book.

Raises:

get_encoded()[source]

Gets the Base64 encoded string and the file format of this certificate.

Authorization requirements:

Object-access permission to this Certificate.

Returns:

The encoded certificate in conjunction with its format:

key “certificate”: The Base64 encoded string of the certificate.
key “format”: The format of the certificate (“der” or “pem”).

Return type:

dict

Raises:

dump()[source]

Dump this Certificate resource with its properties as a resource definition.

The returned resource definition has the following format:

{
    # Resource properties:
    "properties": {...},
}

Returns:: Resource definition of this resource.
Return type:: dict