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:

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

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

Authorization requirements:

  • Object-access permission to any CPC to be included in the result.
Parameters:
  • full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation.
  • filter_args (dict) –

    Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering.

    None causes no filtering to happen, i.e. all resources are returned.
Returns:

A list of Cpc objects.
Raises:
class zhmcclient.Cpc(manager, uri, name=None, properties=None)[source]

Representation of a managed CPC.

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

Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case, CpcManager).

lpars

LparManager – Access to the LPARs in this CPC.

partitions

PartitionManager – Access to the Partitions in this CPC.

adapters

AdapterManager – Access to the Adapters in this CPC.

virtual_switches

VirtualSwitchManager – Access to the Virtual Switches in this CPC.

vswitches

VirtualSwitchManager – 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.

reset_activation_profiles

ActivationProfileManager – Access to the Reset Activation Profiles in this CPC.

image_activation_profiles

ActivationProfileManager – Access to the Image Activation Profiles in this CPC.

load_activation_profiles

ActivationProfileManager – Access to the Load Activation Profiles in this CPC.

dpm_enabled

bool – 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:
maximum_active_partitions

Integer – The maximum number of active logical partitions or partitions of this CPC.

The following table shows the maximum number of active logical partitions or partitions by machine generations supported at the HMC API:

Machine generation Maximum partitions
z196 60
z114 30
zEC12 60
zBC12 30
z13 / Emperor 85
z13s / Rockhopper 40
z14 85
Raises:
update_properties(properties)[source]

Update writeable properties of this CPC.

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

Authorization requirements:

  • Object-access permission to this CPC.
  • Task permission for the “Start (start a single DPM system)” task.
Parameters:
  • wait_for_completion (bool) –

    Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows:

    • If True, this method will wait for completion of the asynchronous job performing the operation.
    • If False, this method will return immediately once the HMC has accepted the request to perform the operation.
  • operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a OperationTimeout is raised.
Returns:

If wait_for_completion is True, returns None.

If wait_for_completion is False, returns a Job object representing the asynchronously executing job on the HMC.
Return type:

None or Job
Raises:
stop(wait_for_completion=True, operation_timeout=None)[source]

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

Authorization requirements:

  • Object-access permission to this CPC.
  • Task permission for the “Stop (stop a single DPM system)” task.
Parameters:
  • wait_for_completion (bool) –

    Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows:

    • If True, this method will wait for completion of the asynchronous job performing the operation.
    • If False, this method will return immediately once the HMC has accepted the request to perform the operation.
  • operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a OperationTimeout is raised.
Returns:

If wait_for_completion is True, returns None.

If wait_for_completion is False, returns a Job object representing the asynchronously executing job on the HMC.
Return type:

None or Job
Raises:
import_profiles(profile_area, wait_for_completion=True, operation_timeout=None)[source]

Import activation profiles and/or system activity profiles for this CPC from the SE hard drive into the CPC using the HMC operation “Import Profiles”.

This operation is not permitted when the CPC is in DPM mode.

Authorization requirements:

  • Object-access permission to this CPC.
  • Task permission for the “CIM Actions ExportSettingsData” task.
Parameters:
  • profile_area (int) – The numbered hard drive area (1-4) from which the profiles are imported.
  • wait_for_completion (bool) –

    Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows:

    • If True, this method will wait for completion of the asynchronous job performing the operation.
    • If False, this method will return immediately once the HMC has accepted the request to perform the operation.
  • operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a OperationTimeout is raised.
Returns:

If wait_for_completion is True, returns None.

If wait_for_completion is False, returns a Job object representing the asynchronously executing job on the HMC.
Return type:

None or Job
Raises:
export_profiles(profile_area, wait_for_completion=True, operation_timeout=None)[source]

Export activation profiles and/or system activity profiles from this CPC to the SE hard drive using the HMC operation “Export Profiles”.

This operation is not permitted when the CPC is in DPM mode.

Authorization requirements:

  • Object-access permission to this CPC.
  • Task permission for the “CIM Actions ExportSettingsData” task.
Parameters:
  • profile_area (int) – The numbered hard drive area (1-4) to which the profiles are exported. Any existing data is overwritten.
  • wait_for_completion (bool) –

    Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows:

    • If True, this method will wait for completion of the asynchronous job performing the operation.
    • If False, this method will return immediately once the HMC has accepted the request to perform the operation.
  • operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a OperationTimeout is raised.
Returns:

If wait_for_completion is True, returns None.

If wait_for_completion is False, returns a Job object representing the asynchronously executing job on the HMC.
Return type:

None or Job
Raises:
get_wwpns(partitions)[source]

Return the WWPNs of the host ports (of the HBAs) of the specified Partitions of this CPC.

This method performs the HMC operation “Export WWPN List”.

Authorization requirements:

  • Object-access permission to this CPC.
  • Object-access permission to the Partitions designated by the “partitions” parameter.
  • Task permission for the “Export WWPNs” task.
Parameters:

partitions (iterable of Partition) – Partitions to be used.
Returns:

A list of items for each WWPN, where each item is a dict with the following keys:

  • ’partition-name’ (string): Name of the Partition.
  • ’adapter-id’ (string): ID of the FCP Adapter.
  • ’device-number’ (string): Virtual device number of the HBA.
  • ’wwpn’ (string): WWPN of the HBA.
Raises:
get_free_crypto_domains(crypto_adapters=None)[source]

Return a list of crypto domains that are free for usage on a list of crypto adapters in this CPC.

A crypto domain is considered free for usage if it is not assigned to any defined partition of this CPC in access mode ‘control-usage’ on any of the specified crypto adapters.

For this test, all currently defined partitions of this CPC are checked, regardless of whether or not they are active. This ensures that a crypto domain that is found to be free for usage can be assigned to a partition for ‘control-usage’ access to the specified crypto adapters, without causing a crypto domain conflict when activating that partition.

Note that a similar notion of free domains does not exist for access mode ‘control’, because a crypto domain on a crypto adapter can be in control access by multiple active partitions.

This method requires the CPC to be in DPM mode.

Example:

            crypto domains
adapters     0   1   2   3
           +---+---+---+---+
  c1       |A,c|a,c|   | C |
           +---+---+---+---+
  c2       |b,c|B,c| B | C |
           +---+---+---+---+

In this example, the CPC has two crypto adapters c1 and c2. For simplicity of the example, we assume these crypto adapters support only 4 crypto domains.

Partition A uses only adapter c1 and has domain 0 in ‘control-usage’ access (indicated by an upper case letter ‘A’ in the corresponding cell) and has domain 1 in ‘control’ access (indicated by a lower case letter ‘a’ in the corresponding cell).

Partition B uses only adapter c2 and has domain 0 in ‘control’ access and domains 1 and 2 in ‘control-usage’ access.

Partition C uses both adapters, and has domains 0 and 1 in ‘control’ access and domain 3 in ‘control-usage’ access.

The domains free for usage in this example are shown in the following table, for each combination of crypto adapters to be investigated:

crypto_adapters domains free for usage
c1 1, 2
c2 0
c1, c2 (empty list)

Experimental: This method has been added in v0.14.0 and is currently considered experimental. Its interface may change incompatibly. Once the interface remains stable, this experimental marker will be removed.

Authorization requirements:

  • Object-access permission to this CPC.
  • Object-access permission to all of its Partitions.
  • Object-access permission to all of its crypto Adapters.
Parameters:

crypto_adapters (iterable of Adapter) –

The crypto Adapters to be investigated.

None means to investigate all crypto adapters of this CPC.
Returns:

A sorted list of domain index numbers (integers) of the crypto domains that are free for usage on the specified crypto adapters.

Returns None, if crypto_adapters was an empty list or 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.
Return type:

None or Job
Raises:
set_power_capping(power_capping_state, power_cap=None, wait_for_completion=True, operation_timeout=None)[source]

Set the power capping settings of this CPC. The power capping settings of a CPC define whether or not the power consumption of the CPC is limited and if so, what the limit is. Use this method to limit the peak power consumption of a CPC, or to remove a power consumption limit for a CPC.

The current power capping settings in effect for a CPC are described in the “cpc-power-capping-state” and “cpc-power-cap-current” properties of the CPC.

This method performs the HMC operation “Set CPC Power Capping”. It requires that the feature “Automate/advanced management suite” (FC 0020) is installed and enabled, and fails otherwise.

This method will also fail if the CPC is under group control.

Whether a CPC currently allows this method is described in the “cpc-power-cap-allowed” property of the CPC.

Authorization requirements:

  • Object-access permission to this CPC.
  • Task permission for the “Power Capping” task.
Parameters:
  • power_capping_state (string) –

    The power capping state to be set, with the possible values:

    • ”disabled” - The power cap of the CPC is not set and the peak power consumption is not limited. This is the default setting.
    • ”enabled” - The peak power consumption of the CPC is limited to the specified power cap value.
    • ”custom” - Individually configure the components for power capping. No component settings are actually changed when this mode is entered.
  • power_cap (integer) –

    The power cap value to be set, as a power consumption in Watt. This parameter is required not to be None if power_capping_state=”enabled”.

    The specified value must be between the values of the CPC properties “cpc-power-cap-minimum” and “cpc-power-cap-maximum”.

  • wait_for_completion (bool) –

    Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows:

    • If True, this method will wait for completion of the asynchronous job performing the operation.
    • If False, this method will return immediately once the HMC has accepted the request to perform the operation.
  • operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a OperationTimeout is raised.
Returns:

If wait_for_completion is True, returns None.

If wait_for_completion is False, returns a Job object representing the asynchronously executing job on the HMC.
Return type:

None or Job
Raises:
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

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:

console

Console – Console defining the scope for this manager.

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

List the unmanaged CPCs exposed by the HMC this client is connected to.

Because the CPCs are unmanaged, the returned UnmanagedCpc objects cannot perform any operations and will have only the following properties:

  • object-uri
  • name

Authorization requirements:

  • None
Parameters:
  • full_properties (bool) – Ignored (exists for consistency with other list() methods).
  • filter_args (dict) –

    Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering.

    None causes no filtering to happen, i.e. all resources are returned.
Returns:

A list of UnmanagedCpc objects.
Raises:
class zhmcclient.UnmanagedCpc(manager, uri, name=None, properties=None)[source]

Representation of an unmanaged CPC.

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

Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case, UnmanagedCpcManager).

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

  1. 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.
  2. 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.
  3. 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):

cpc

Cpc – CPC defining the scope for this manager.

profile_type

string – Type of the Activation Profiles managed by this object:

  • 'reset' - Reset Activation Profiles
  • 'image' - Image Activation Profiles
  • 'load' - Load Activation Profiles
list(full_properties=False, filter_args=None)[source]

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

Authorization requirements:

  • Object-access permission to this CPC.
Parameters:
  • full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation.
  • filter_args (dict) –

    Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering.

    None causes no filtering to happen, i.e. all resources are returned.
Returns:

A list of ActivationProfile objects.
Raises:
class zhmcclient.ActivationProfile(manager, uri, name=None, properties=None)[source]

Representation of an Activation Profile of a particular type.

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

Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case, ActivationProfileManager).

update_properties(properties)[source]

Update writeable properties of this Activation Profile.

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:

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

cpc

Cpc – CPC defining the scope for this manager.

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

List the LPARs in this CPC.

Authorization requirements:

  • Object-access permission to this CPC.
  • Object-access permission to any LPAR to be included in the result.
Parameters:
  • full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation.
  • filter_args (dict) –

    Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering.

    None causes no filtering to happen, i.e. all resources are returned.
Returns:

A list of Lpar objects.
Raises:
class zhmcclient.Lpar(manager, uri, name=None, properties=None)[source]

Representation of an LPAR.

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

Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case, LparManager).

update_properties(properties)[source]

Update writeable properties of this LPAR.

Authorization requirements:

  • Object-access permission to this LPAR.
  • Task permission for the “Change Object Definition” task.
  • Object-access permission to the CPC of this LPAR.
  • For an LPAR whose activation-mode is “zaware”, task permission for the “Firmware 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 ‘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 takes a few seconds until the LPAR status has reached the desired value. If wait_for_completion=True, this method repeatedly checks the status of the LPAR after the HMC operation has completed, and waits until the status is in the desired state “not-operating” (which indicates that the LPAR is active but no operating system is running), or if allow_status_exceptions was set additionally in the state “exceptions”.

Authorization requirements:

  • Object-access permission to the CPC containing this LPAR.
  • Object-access permission to 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 in addition “exceptions”, if allow_status_exceptions was set.
    • If False, this method will return immediately once the HMC has accepted the request to perform the operation.
  • operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a OperationTimeout is raised.
  • status_timeout (number) – Timeout in seconds, for waiting that the status of the LPAR has reached the desired status, after the HMC operation has completed. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a StatusTimeout is raised.
  • allow_status_exceptions (bool) – Boolean controlling whether LPAR status “ecxeptions” is considered an additional acceptable end status when wait_for_completion is set.
  • activation_profile_name (string) –

    Name of the image ActivationProfile to use for activation.

    None means that the activation profile specified in the next-activation-profile-name property of the LPAR is used.

  • force (bool) –

    Boolean controlling whether this operation is permitted when the LPAR is in the “operating” status.

    TBD: What will happen with the LPAR in that case (deactivated then activated? nothing?)
Returns:

If wait_for_completion is True, returns None.

If wait_for_completion is False, returns a Job object representing the asynchronously executing job on the HMC.
Return type:

None or Job
Raises:
deactivate(wait_for_completion=True, operation_timeout=None, status_timeout=None, allow_status_exceptions=False, force=False)[source]

De-activate (stop) this LPAR, using the HMC operation “Deactivate Logical Partition”.

This HMC operation has deferred status behavior: If the asynchronous job on the HMC is complete, it takes a few seconds until the LPAR status has reached the desired value. If wait_for_completion=True, this method repeatedly checks the status of the LPAR after the HMC operation has completed, and waits until the status is in the desired state “not-activated”, or if allow_status_exceptions was set additionally in the state “exceptions”.

Authorization requirements:

  • Object-access permission to the CPC containing this LPAR.
  • Object-access permission to this LPAR.
  • Task permission for the “Deactivate” task.
Parameters:
  • wait_for_completion (bool) –

    Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows:

    • If True, this method will wait for completion of the asynchronous job performing the operation, and for the status becoming “non-activated” (or in addition “exceptions”, if allow_status_exceptions was set.
    • If False, this method will return immediately once the HMC has accepted the request to perform the operation.
  • operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a OperationTimeout is raised.
  • status_timeout (number) – Timeout in seconds, for waiting that the status of the LPAR has reached the desired status, after the HMC operation has completed. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a StatusTimeout is raised.
  • allow_status_exceptions (bool) – Boolean controlling whether LPAR status “ecxeptions” is considered an additional acceptable end status when wait_for_completion is set.
  • force (bool) –

    Boolean controlling whether this operation is permitted when the LPAR is in the “operating” status.

    TBD: What will happen with the LPAR in that case (deactivated then activated? nothing?)
Returns:

If wait_for_completion is True, returns None.

If wait_for_completion is False, returns a Job object representing the asynchronously executing job on the HMC.
Return type:

None or Job
Raises:
load(load_address=None, load_parameter=None, 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 the CPC containing this LPAR.
  • Object-access permission to 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.
  • wait_for_completion (bool) –

    Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows:

    • If True, this method will wait for completion of the asynchronous job performing the operation, and for the status becoming “operating” (or in addition “exceptions”, if allow_status_exceptions was set.
    • If False, this method will return immediately once the HMC has accepted the request to perform the operation.
  • operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a OperationTimeout is raised.
  • status_timeout (number) – Timeout in seconds, for waiting that the status of the LPAR has reached the desired status, after the HMC operation has completed. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a StatusTimeout is raised.
  • allow_status_exceptions (bool) – Boolean controlling whether LPAR status “ecxeptions” is considered an additional acceptable end status when wait_for_completion is set.
  • force (bool) –

    Boolean controlling whether this operation is permitted when the LPAR is in the “operating” status.

    TBD: What will happen with the LPAR in that case (deactivated then activated? nothing?)
Returns:

If wait_for_completion is True, returns None.

If wait_for_completion is False, returns a Job object representing the asynchronously executing job on the HMC.
Return type:

None or Job
Raises:
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.

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.

Parameters:
  • os_command_text (string) – The text of the operating system command.
  • is_priority (bool) –

    Boolean controlling whether this is a priority operating system command, as follows:

    • If True, this message is treated as a priority operating system command.
    • If False, this message is not treated as a priority operating system command. The default.
Returns:

None
Raises:
wait_for_status(status, status_timeout=None)[source]

Wait until the status of this 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:

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

cpc

Cpc – CPC defining the scope for this manager.

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

List the Partitions in this CPC.

Authorization requirements:

  • Object-access permission to this CPC.
  • Object-access permission to any Partition to be included in the result.
Parameters:
  • full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation.
  • filter_args (dict) –

    Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering.

    None causes no filtering to happen, i.e. all resources are returned.
Returns:

A list of Partition objects.
Raises:
create(properties)[source]

Create and configure a Partition in this CPC.

Authorization requirements:

  • Object-access permission to this CPC.
  • Task permission to the “New Partition” task.
Parameters:

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

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

Partition
Raises:
partition_object(part_id)[source]

Return a minimalistic Partition object for a Partition in this CPC.

This method is an internal helper function and is not normally called by users.

This object will be connected in the Python object tree representing the resources (i.e. it has this CPC as a parent), and will have the following properties set:

  • object-uri
  • object-id
  • parent
  • class
Parameters:part_id (string) – object-id of the Partition
Returns:A Python object representing the Partition.
Return type:Partition
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).

nics

NicManager – Access to the NICs in this Partition.

hbas

HbaManager – Access to the HBAs in this Partition.

virtual_functions

VirtualFunctionManager – Access to the Virtual Functions in this Partition.

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.
  • Object-access permission to the CPC containing this Partition.
  • Task permission to the “Start Partition” task.
Parameters:
  • wait_for_completion (bool) –

    Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows:

    • If True, this method will wait for completion of the asynchronous job performing the operation.
    • If False, this method will return immediately once the HMC has accepted the request to perform the operation.
  • operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a OperationTimeout is raised.
  • status_timeout (number) – Timeout in seconds, for waiting that the status of the partition has reached the desired status, after the HMC operation has completed. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a StatusTimeout is raised.
Returns:

If wait_for_completion is True, returns an empty dict object.

If wait_for_completion is False, returns a Job object representing the asynchronously executing job on the HMC.
Return type:

dict or Job
Raises:
stop(wait_for_completion=True, operation_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.
Returns:

If wait_for_completion is True, returns an empty dict object.

If wait_for_completion is False, returns a Job object representing the asynchronously executing job on the HMC.
Return type:

dict or Job
Raises:
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.

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

Authorization requirements:

  • Object-access permission to this Partition.
  • Task permission to the “Dump Partition” task.
Parameters:
  • parameters (dict) – Input parameters for the operation. Allowable input parameters are defined in section ‘Request body contents’ in section ‘Dump Partition’ in the HMC API book.
  • wait_for_completion (bool) –

    Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows:

    • If True, this method will wait for completion of the asynchronous job performing the operation.
    • If False, this method will return immediately once the HMC has accepted the request to perform the operation.
  • operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a OperationTimeout is raised.
Returns:

If wait_for_completion is True, returns an empty dict object.

If wait_for_completion is False, returns a Job object representing the asynchronously executing job on the HMC.
Return type:

dict or Job
Raises:
psw_restart(wait_for_completion=True, operation_timeout=None)[source]

Initiates a PSW restart for this Partition, using the HMC operation ‘Perform PSW Restart’.

Authorization requirements:

  • Object-access permission to this Partition.
  • Task permission to the “PSW Restart” task.
Parameters:
  • wait_for_completion (bool) –

    Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows:

    • If True, this method will wait for completion of the asynchronous job performing the operation.
    • If False, this method will return immediately once the HMC has accepted the request to perform the operation.
  • operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a OperationTimeout is raised.
Returns:

If wait_for_completion is True, returns an empty dict object.

If wait_for_completion is False, returns a Job object representing the asynchronously executing job on the HMC.
Return type:

dict or Job
Raises:
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.

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.

Parameters:
  • os_command_text (string) – The text of the operating system command.
  • is_priority (bool) –

    Boolean controlling whether this is a priority operating system command, as follows:

    • If True, this message is treated as a priority operating system command.
    • If False, this message is not treated as a priority operating system command. The default.
Returns:

None
Raises:
wait_for_status(status, status_timeout=None)[source]

Wait until the status of this partition has a desired value.

Parameters:
  • status (string or iterable of string) – Desired partition status or set of status values to reach; one or more of the values defined for the ‘status’ property in the data model for partitions in the HMC API book.
  • status_timeout (number) – Timeout in seconds, for waiting that the status of the partition has reached one of the desired status values. The special value 0 means that no timeout is set. None means that the default status timeout will be used. If the timeout expires, a StatusTimeout is raised.
Raises:
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.
  • 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.
  • 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:
Raises:

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

  1. 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.
  2. 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.
  3. 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.
  4. 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):

cpc

Cpc – CPC defining the scope for this manager.

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

List the Adapters in this CPC.

Authorization requirements:

  • Object-access permission to this CPC.
  • Object-access permission to any Adapter to be included in the result.
Parameters:
  • full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation.
  • filter_args (dict) –

    Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering.

    None causes no filtering to happen, i.e. all resources are returned.
Returns:

A list of Adapter objects.
Raises:
create_hipersocket(properties)[source]

Create and configure a HiperSockets Adapter in this CPC.

Authorization requirements:

  • Object-access permission to the scoping CPC.
  • Task permission to the “Create HiperSockets Adapter” task.
Parameters:

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

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

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

ports

PortManager – Access to the Ports of this Adapter.

port_uris_prop

string – 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.

port_uri_segment

string – 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.

maximum_crypto_domains

Integer – 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 machines in DPM mode:

Adapter type Machine generation Maximum domains
Crypto Express 5S z14 / z13 / Emperor 85
Crypto Express 5S z13s / Rockhopper 40
Crypto Express 6S z14 85

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

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

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

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:

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

adapter

Adapter – Adapter defining the scope for this manager.

port_type

string – 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
list(full_properties=False, filter_args=None)[source]

List the Ports of this Adapter.

If the adapter does not have any ports, an empty list is returned.

Authorization requirements:

  • Object-access permission to this Adapter.
Parameters:
  • full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation.
  • filter_args (dict) –

    Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering.

    None causes no filtering to happen, i.e. all resources are returned.
Returns:

A list of Port objects.
Raises:
class zhmcclient.Port(manager, uri, name=None, properties=None)[source]

Representation of a Port.

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

For the properties of a Port, see section ‘Data model - Port Element Object’ in section ‘Adapter object’ in the HMC API book.

Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case, PortManager).

update_properties(properties)[source]

Update writeable properties of this Port.

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:

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

partition

Partition – Partition defining the scope for this manager.

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

List the NICs in this Partition.

Authorization requirements:

  • Object-access permission to this Partition.
Parameters:
  • full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation.
  • filter_args (dict) –

    Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering.

    None causes no filtering to happen, i.e. all resources are returned.
Returns:

A list of Nic objects.
Raises:
create(properties)[source]

Create and configure a NIC in this Partition.

The NIC must be backed by an adapter port (on an OSA, ROCE, or Hipersockets adapter).

The way the backing adapter port is specified in the “properties” parameter of this method depends on the adapter type, as follows:

  • For OSA and Hipersockets adapters, the “virtual-switch-uri” property is used to specify the URI of the virtual switch that is associated with the backing adapter port.

    This virtual switch is a resource that automatically exists as soon as the adapter resource exists. Note that these virtual switches do not show up in the HMC GUI; but they do show up at the HMC REST API and thus also at the zhmcclient API as the VirtualSwitch class.

    The value for the “virtual-switch-uri” property can be determined from a given adapter name and port index as shown in the following example code (omitting any error handling):

    partition = ...  # Partition object for the new NIC

adapter_name = 'OSA #1'  # name of adapter with backing port
adapter_port_index = 0   # port index of backing port

adapter = partition.manager.cpc.adapters.find(name=adapter_name)

vswitches = partition.manager.cpc.virtual_switches.findall(
    **{'backing-adapter-uri': adapter.uri})

vswitch = None
for vs in vswitches:
    if vs.get_property('port') == adapter_port_index:
        vswitch = vs
        break

properties['virtual-switch-uri'] = vswitch.uri

  • For RoCE adapters, the “network-adapter-port-uri” property is used to specify the URI of the backing adapter port, directly.

    The value for the “network-adapter-port-uri” property can be determined from a given adapter name and port index as shown in the following example code (omitting any error handling):

    partition = ...  # Partition object for the new NIC

adapter_name = 'ROCE #1'  # name of adapter with backing port
adapter_port_index = 0   # port index of backing port

adapter = partition.manager.cpc.adapters.find(name=adapter_name)

port = adapter.ports.find(index=adapter_port_index)

properties['network-adapter-port-uri'] = port.uri

Authorization requirements:

  • Object-access permission to this Partition.
  • Object-access permission to the backing Adapter for the new NIC.
  • Task permission to the “Partition Details” task.
Parameters:

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

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

Nic
Raises:
nic_object(nic_id)[source]

Return a minimalistic Nic object for a Nic in this Partition.

This method is an internal helper function and is not normally called by users.

This object will be connected in the Python object tree representing the resources (i.e. it has this Partition as a parent), and will have the following properties set:

  • element-uri
  • element-id
  • parent
  • class
Parameters:nic_id (string) – element-id of the Nic
Returns:A Python object representing the Nic.
Return type:Nic
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).

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.

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:

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

HBAs only exist in CPCs that are in DPM mode.

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

partition

Partition – Partition defining the scope for this manager.

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

List the HBAs in this Partition.

The returned HBAs have only the ‘element-uri’ property set.

Filtering is supported only for the ‘element-uri’ property.

Authorization requirements:

  • Object-access permission to this Partition.
Parameters:
  • full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation.
  • filter_args (dict) –

    Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering.

    None causes no filtering to happen, i.e. all resources are returned.
Returns:

A list of Hba objects.
Raises:
create(properties)[source]

Create and configure an HBA in this Partition.

The HBA must be backed by an adapter port on an FCP adapter.

The backing adapter port is specified in the “properties” parameter of this method by setting the “adapter-port-uri” property to the URI of the backing adapter port.

The value for the “adapter-port-uri” property can be determined from a given adapter name and port index as shown in the following example code (omitting any error handling):

partition = ...  # Partition object for the new HBA

adapter_name = 'FCP #1'  # name of adapter with backing port
adapter_port_index = 0   # port index of backing port

adapter = partition.manager.cpc.adapters.find(name=adapter_name)

port = adapter.ports.find(index=adapter_port_index)

properties['adapter-port-uri'] = port.uri

Authorization requirements:

  • Object-access permission to this Partition.
  • Object-access permission to the backing Adapter for the new HBA.
  • Task permission to the “Partition Details” task.
Parameters:

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

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

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

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.

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:

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

partition

Partition – Partition defining the scope for this manager.

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

List the Virtual Functions of this Partition.

Authorization requirements:

  • Object-access permission to this Partition.
Parameters:
  • full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation.
  • filter_args (dict) –

    Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering.

    None causes no filtering to happen, i.e. all resources are returned.
Returns:

A list of VirtualFunction objects.
Raises:
create(properties)[source]

Create a Virtual Function in this Partition.

Authorization requirements:

  • Object-access permission to this Partition.
  • Object-access permission to the backing accelerator Adapter.
  • Task permission for the “Partition Details” task.
Parameters:

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

The resource object for the new Virtual Function. The object will have its ‘element-uri’ property set as returned by the HMC, and will also have the input properties set.
Return type:

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

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.

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

cpc

Cpc – CPC defining the scope for this manager.

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

List the Virtual Switches in this CPC.

Authorization requirements:

  • Object-access permission to this CPC.
  • Object-access permission to the backing Adapters of any Virtual Switches to be included in the result.
Parameters:
  • full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation.
  • filter_args (dict) –

    Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering.

    None causes no filtering to happen, i.e. all resources are returned.
Returns:

A list of VirtualSwitch objects.
Raises:
class zhmcclient.VirtualSwitch(manager, uri, name=None, properties=None)[source]

Representation of a Virtual Switch.

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

For the properties of a Virtual Switch, see section ‘Data model’ in section ‘Virtual Switch object’ in the HMC API book.

Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case, VirtualSwitchManager).

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.

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

client

Client – The client defining the scope for this manager.

list(full_properties=True, filter_args=None)[source]

List the (one) Console representing the HMC this client is connected to.

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

users

UserManager – Access to the Users in this Console.

user_roles

UserRoleManager – Access to the User Roles in this Console.

user_patterns

UserPatternManager – Access to the User Patterns in this Console.

password_rules

PasswordRuleManager – Access to the Password Rules in this Console.

tasks

TaskManager – Access to the Tasks in this Console.

ldap_server_definitions

LdapServerDefinitionManager – Access to the LDAP Server Definitions in this Console.

unmanaged_cpcs

UnmanagedCpcManager – Access to the unmanaged CPCs in this Console.

restart(force=False, wait_for_available=True, operation_timeout=None)[source]

Restart the HMC represented by this Console object.

Once the HMC is online again, this Console object, as well as any other resource objects accessed through this HMC, can continue to be used. An automatic re-logon will be performed under the covers, because the HMC restart invalidates the currently used HMC session.

Authorization requirements:

  • Task permission for the “Shutdown/Restart” task.
  • “Remote Restart” must be enabled on the HMC.
Parameters:
  • force (bool) – Boolean controlling whether the restart operation is processed when users are connected (True) or not (False). Users in this sense are local or remote GUI users. HMC WS API clients do not count as users for this purpose.
  • wait_for_available (bool) –

    Boolean controlling whether this method should wait for the HMC to become available again after the restart, as follows:

    • If True, this method will wait until the HMC has restarted and is available again. The query_api_version() method will be used to check for availability of the HMC.
    • If False, this method will return immediately once the HMC has accepted the request to be restarted.
  • operation_timeout (number) – Timeout in seconds, for waiting for HMC availability after the restart. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_available=True, a OperationTimeout is raised.
Raises:
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:

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

console

Console – Console defining the scope for this manager.

list(full_properties=True, filter_args=None)[source]

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

Authorization requirements:

  • User-related-access permission to the User object included in the result, or, depending on the type of User object, task permission to the “Manage Users” task or the “Manage User Templates” task.
Parameters:
  • full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation.
  • filter_args (dict) –

    Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering.

    None causes no filtering to happen, i.e. all resources are returned.
Returns:

A list of User objects.
Raises:
create(properties)[source]

Create a new User in this HMC.

Authorization requirements:

  • Task permission to the “Manage Users” task to create a standard user or the “Manage User Templates” task to create a template user.
Parameters:

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

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

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

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.

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

console

Console – Console defining the scope for this manager.

list(full_properties=True, filter_args=None)[source]

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

Authorization requirements:

  • User-related-access permission to the User Role objects included in the result, or task permission to the “Manage User Roles” task.
Parameters:
  • full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation.
  • filter_args (dict) –

    Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering.

    None causes no filtering to happen, i.e. all resources are returned.
Returns:

A list of UserRole objects.
Raises:
create(properties)[source]

Create a new (user-defined) User Role in this HMC.

Authorization requirements:

  • Task permission to the “Manage User Roles” task.
Parameters:

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

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

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

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.

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=False, view_only=True)[source]

Add permission for the specified permitted object(s) to this User Role, thereby granting that permission to all users that have this User Role.

The granted permission depends on the resource class of the permitted object(s):

  • For Task resources, the granted permission is task permission for that task.
  • For Group resources, the granted permission is object access permission for the group resource, and optionally also for the group members.
  • For any other resources, the granted permission is object access permission for these resources.

The User Role must be user-defined.

Authorization requirements:

  • Task permission to the “Manage User Roles” task.
Parameters:
  • permitted_object (BaseResource or string) –

    Permitted object(s), either as a Python resource object (e.g. Partition), or as a resource class string (e.g. ‘partition’).

    Must not be None.

  • include_members (bool) –

    Controls whether for Group resources, the operation applies additionally to its group member resources.

    This parameter will be ignored when the permitted object does not specify Group resources.

  • view_only (bool) –

    Controls whether for Task resources, the operation aplies to the view-only version of the task (if True), or to the full version of the task (if False). Only certain tasks support a view-only version.

    This parameter will be ignored when the permitted object does not specify Task resources.
Raises:
remove_permission(permitted_object, include_members=False, view_only=True)[source]

Remove permission for the specified permitted object(s) from this User Role, thereby no longer granting that permission to all users that have this User Role.

The granted permission depends on the resource class of the permitted object(s):

  • For Task resources, the granted permission is task permission for that task.
  • For Group resources, the granted permission is object access permission for the group resource, and optionally also for the group members.
  • For any other resources, the granted permission is object access permission for these resources.

The User Role must be user-defined.

Authorization requirements:

  • Task permission to the “Manage User Roles” task.
Parameters:
  • permitted_object (BaseResource or string) –

    Permitted object(s), either as a Python resource object (e.g. Partition), or as a resource class string (e.g. ‘partition’).

    Must not be None.

  • include_members (bool) –

    Controls whether for Group resources, the operation applies additionally to its group member resources.

    This parameter will be ignored when the permitted object does not specify Group resources.

  • view_only (bool) –

    Controls whether for Task resources, the operation aplies to the view-only version of the task (if True), or to the full version of the task (if False). Only certain tasks support a view-only version.

    This parameter will be ignored when the permitted object does not specify Task resources.
Raises:

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

console

Console – Console defining the scope for this manager.

list(full_properties=True, filter_args=None)[source]

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

Authorization requirements:

  • User-related-access permission to the User Pattern objects included in the result, or task permission to the “Manage User Patterns” task.
Parameters:
  • full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation.
  • filter_args (dict) –

    Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering.

    None causes no filtering to happen, i.e. all resources are returned.
Returns:

A list of UserPattern objects.
Raises:
create(properties)[source]

Create a new User Pattern in this HMC.

Authorization requirements:

  • Task permission to the “Manage User Patterns” task.
Parameters:

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

The resource object for the new User Pattern. The object will have its ‘element-uri’ property set as returned by the HMC, and will also have the input properties set.
Return type:

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

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.

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

console

Console – Console defining the scope for this manager.

list(full_properties=True, filter_args=None)[source]

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

Authorization requirements:

  • User-related-access permission to the Password Rule objects included in the result, or task permission to the “Manage Password Rules” task.
Parameters:
  • full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation.
  • filter_args (dict) –

    Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering.

    None causes no filtering to happen, i.e. all resources are returned.
Returns:

A list of PasswordRule objects.
Raises:
create(properties)[source]

Create a new Password Rule in this HMC.

Authorization requirements:

  • Task permission to the “Manage Password Rules” task.
Parameters:

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

The resource object for the new Password Rule. The object will have its ‘element-uri’ property set as returned by the HMC, and will also have the input properties set.
Return type:

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

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.

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

console

Console – Console defining the scope for this manager.

list(full_properties=True, filter_args=None)[source]

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

Authorization requirements:

  • None
Parameters:
  • full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation.
  • filter_args (dict) –

    Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering.

    None causes no filtering to happen, i.e. all resources are returned.
Returns:

A list of Task objects.
Raises:
class zhmcclient.Task(manager, uri, name=None, properties=None)[source]

Representation of a Task.

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

Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case, TaskManager).

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

console

Console – Console defining the scope for this manager.

list(full_properties=True, filter_args=None)[source]

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

Authorization requirements:

  • User-related-access permission to the LDAP Server Definition objects included in the result, or task permission to the “Manage LDAP Server Definitions” task.
Parameters:
  • full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation.
  • filter_args (dict) –

    Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering.

    None causes no filtering to happen, i.e. all resources are returned.
Returns:

A list of LdapServerDefinition objects.
Raises:
create(properties)[source]

Create a new LDAP Server Definition in this HMC.

Authorization requirements:

  • Task permission to the “Manage LDAP Server Definitions” task.
Parameters:

properties (dict) – Initial property values. Allowable properties are defined in section ‘Request body contents’ in section ‘Create LDAP Server Definition’ in the HMC API book.
Returns:

The resource object for the new LDAP Server Definition. The object will have its ‘object-uri’ property set as returned by the HMC, and will also have the input properties set.
Return type:

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

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.

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: