Execute an arbitrary HMC CLI command over SSH and return its output.

WARNING: This tool executes arbitrary commands on the HMC with the credentials configured in HMC_USER / HMC_PASSWORD (or HMC_SSH_KEY_FILE). It is an operator escape-hatch equivalent to Ansible hmc_command. Use only for HMC CLI operations that have no dedicated MCP tool.

Authentication follows the same env-var configuration as all other tools: set HMC_SSH_KEY_FILE to use key-based auth, otherwise password auth is used.

Reference: https://www.ibm.com/docs/en/power10/7063-CR1?topic=hmc-commands

Get HMC version, network configuration and links to managed systems.

Useful as a connectivity check — this is the cheapest HMC call.

List all managed systems or get one by name or UUID.

When system_name_or_uuid is omitted, returns a list of all managed systems known to the HMC — each entry has UUID, SystemName, State, MTMS (machine type/model/serial), IPAddress, etc.

When system_name_or_uuid is provided, accepts either a SystemName or a UUID and returns the full details dict for that one system, or None if not found.

When state is provided and system_name_or_uuid is omitted, returns only systems whose State property matches the given value, using the HMC server-side search endpoint.

List logical partitions (LPARs) or get/find one.

Resolution priority (first match wins):

1. lpar_name_or_uuid + state_only=True → str | None — current LPAR state only (uses the cheap quick-property endpoint instead of a full fetch).

2. lpar_name_or_uuid → dict | None — full LPAR details. Accepts either a PartitionName or a UUID. When both lpar_name_or_uuid and name are supplied, lpar_name_or_uuid takes priority and name is ignored.

3. name → dict | None — find by PartitionName (exact match).

4. system_name_or_uuid → list[dict] — all LPARs on that system. Accepts either a SystemName or a UUID.

5. state → list[dict] — all LPARs whose PartitionState matches the given value (server-side /search/ endpoint).

6. (no arguments) → list[dict] — all LPARs known to the HMC.

Raises ValueError if state_only=True is supplied without lpar_name_or_uuid. The state filter is ignored when lpar_name_or_uuid or system_name_or_uuid is supplied.

List Virtual I/O Servers or get storage-detail mappings for one.

When vios_name_or_uuid is provided, accepts either a PartitionName or a UUID and returns the VIOS device mapping facts (vSCSI, NPIV, virtual optical) for that VIOS.

When vios_name_or_uuid is omitted, returns a list of all VIOS entries, optionally restricted to one managed system via system_name_or_uuid (accepts either a SystemName or a UUID).

When state is provided and vios_name_or_uuid is omitted, returns only VIOS entries whose PartitionState matches the given value, using the HMC server-side search endpoint. The state filter is ignored when vios_name_or_uuid or system_name_or_uuid is supplied.

List any uom resource type exposed by the HMC.

Examples: ManagedSystem, LogicalPartition, VirtualIOServer, LogicalPartitionProfile, VirtualSwitch, VirtualNetwork, SharedMemoryPool, SharedProcessorPool, HostEthernetAdapter, SRIOVAdapter, Cluster.

Get the status/result of an HMC job by UUID.

List recent HMC jobs (most recent first, up to limit entries).

Returns a list of parsed job dicts with at minimum JobID and Status. Useful for auditing recent HMC activity — power operations, firmware updates, migrations, etc.

Capacity report: for each managed system, total/assigned/free memory (MiB) and processor units, plus running and total LPAR counts.

Derived by listing all managed systems then fetching the LPAR list for each system to compute assigned resources. Free = total − assigned.

Find managed systems that can host a new LPAR of the given size.

Returns systems with at least desired_memory_mb MiB free and at least desired_proc_units free processor units, sorted by free memory descending. Each result has the same fields as :func:hmc_capacity_report.

Find a managed system by its SystemName (exact match).

Returns the full system dict if found, or None if no system with that name is known to the HMC.

Poll an HMC job until it reaches a terminal state (COMPLETED / FAILED / EXCEPTION).

Returns the final job entry. If timeout_seconds elapses before a terminal state is reached, returns the last-seen entry regardless of status — check the Status field to distinguish timeout from completion.

Create a new LPAR on a managed system.

system_name_or_uuid: the target managed system — accepts either a SystemName (e.g. "Server-9080-M9S-SN12345") or a UUID (find it with hmc_systems). Memory values are in MiB. By default a shared-processor partition is created; set dedicated=True for dedicated CPUs (then procs are whole CPU counts). For shared partitions, procs are processing units (may be fractional, e.g. 0.5) and vcpus are virtual processor counts.

The partition is created powered off with a default profile; storage, network and boot settings still need to be configured (via the HMC UI or profile edits) before it can boot an OS. This creates a real partition — confirm name/system_name_or_uuid before calling.

Raises ValueError if a partition with the given name already exists on any managed system — names must be unique across the HMC.

partition_type must be one of: 'AIX/Linux', 'OS400', 'Virtual IO Server'. os_type: target OS — aix, linux, or ibmi. keylock: initial keylock position — normal, manual, or auto. max_virtual_slots: maximum number of virtual I/O slots.

Modify an LPAR's name and/or resource assignment (memory / CPU).

lpar_name_or_uuid: accepts either a PartitionName or a UUID (find it with hmc_lpars). Only the fields you pass are changed. Memory values are in MiB. For a running partition these are dynamic (DLPAR) operations and require an active RMC connection; otherwise the change applies on next activation. Set dedicated=True to assign whole CPUs, False for shared processing units + virtual processors; omit it to leave the sharing mode unchanged.

DLPAR processor hot-plug: change CPU resources on a running LPAR.

lpar_name_or_uuid: accepts either a PartitionName or a UUID. Posts a minimal PartitionProcessorConfiguration document to the HMC. Only the fields you pass are changed. For shared partitions, procs are processing units (may be fractional, e.g. 0.5); vcpus are virtual processor counts (ints). Set dedicated=True for whole-CPU assignment, False for shared; omit it to leave the sharing mode unchanged.

If the LPAR does not have an active RMC connection, the change is profile-only and takes effect on next activation (no reboot is triggered).

Modify a managed system's configuration.

Only the fields you pass are changed; omitted fields are left as-is.

system_name_or_uuid: the managed system — accepts either a SystemName or a UUID (from hmc_systems). new_name: rename the managed system. power_off_policy: power-off policy — 1 powers the system off after all partitions shut down, 0 leaves it powered on. power_on_lpar_start_policy: LPAR auto-start policy on system power-on — 'autostart', 'userinit', or 'autorecovery'. pend_mem_region_size: pending memory region size (MiB). requested_num_sys_huge_pages: number of huge memory pages to allocate. mem_mirroring_mode: memory mirroring mode — 'none' or 'sys_firmware_only'.

DLPAR memory hot-plug: change memory resources on a running LPAR.

lpar_name_or_uuid: accepts either a PartitionName or a UUID. Posts a minimal PartitionMemoryConfiguration document to the HMC. Memory values are in MiB. Only the fields you pass are changed.

If the LPAR does not have an active RMC connection, the change is profile-only and takes effect on next activation (no reboot is triggered).

Delete (destroy) an LPAR by name or UUID.

The partition must be powered off first (use hmc_power_off_lpar and confirm with hmc_lpars(lpar_name_or_uuid=..., state_only=True)). This tool refuses to delete a partition whose current state is anything other than 'not activated', matching the precondition check pattern used by hmc_remove_memory_pool. This permanently removes the partition and its profiles from the HMC — it is irreversible. Confirm the target with hmc_lpars(name=...) before calling. Returns a confirmation string (immediate delete — no job to poll).

lpar_name_or_uuid: accepts either a PartitionName or a UUID.

Raises: HMCError: If the partition state is not 'not activated' (HTTP 409).

Submit a PowerOn job for a logical partition.

lpar_name_or_uuid: accepts either a PartitionName or a UUID (find it with hmc_lpars). Returns the submitted job (check hmc_get_job for status). This changes the state of a real partition — confirm the target with hmc_lpars(name=...) before calling.

If the partition is already in the 'running' state, the tool returns {"already_running": True, "message": "..."} without submitting a job. Pass force=True to skip this check and submit the PowerOn unconditionally.

Set wait=True to block until the job reaches COMPLETED / FAILED / EXCEPTION (or until timeout_seconds elapses).

Submit a PowerOff job for a logical partition.

lpar_name_or_uuid: accepts either a PartitionName or a UUID. immediate=True forces an immediate power off (no graceful OS shutdown). Returns the submitted job. This changes the state of a real partition.

Set wait=True to block until the job reaches a terminal state.

Power on a managed system (PowerOn job).

system_name_or_uuid: accepts either a SystemName or a UUID (find it with hmc_systems). Set wait=True to block until the job reaches a terminal state.

Power off a managed system (PowerOff job). immediate skips graceful shutdown.

system_name_or_uuid: accepts either a SystemName or a UUID. Set wait=True to block until the job reaches a terminal state.

Power on a VIOS (PowerOn job).

vios_name_or_uuid: accepts either a PartitionName or a UUID (find it with hmc_vios). Set wait=True to block until the job reaches a terminal state.

Power off a VIOS (PowerOff job). immediate skips graceful shutdown.

vios_name_or_uuid: accepts either a PartitionName or a UUID. Set wait=True to block until the job reaches a terminal state.

Create a new Virtual IO Server (VIOS) partition on a managed system.

system_uuid is the target managed system (find it with hmc_systems). Memory values are in MiB; procs are shared processing units (fractional ok). The VIOS is created powered off with default settings — install the OS with hmc_install_vios before using it as a storage/network server. This creates a real partition — confirm name/system_uuid before calling.

Delete (destroy) a VIOS partition by UUID.

The VIOS must be powered off first (use hmc_power_off_vios and confirm with hmc_lpars(vios_uuid=..., state_only=True)). This tool refuses to delete a VIOS whose current state is anything other than 'not activated', matching the precondition check pattern used by hmc_remove_memory_pool. This permanently removes the VIOS and its profiles from the HMC — it is irreversible. Confirm the UUID with hmc_vios before calling. Returns a confirmation string (immediate delete — no job to poll).

Raises: HMCError: If the VIOS state is not 'not activated' (HTTP 409).

Submit a NIM-based VIOS installation job.

vios_uuid is the UUID of an existing (powered-off) VIOS partition. The VIOS will PXE-boot from the NIM server at nim_ip to install its OS. nim_gateway and nim_subnetmask define the network for the NIM install boot; vios_ip is the IP address the VIOS uses during the NIM install; vlan_id is the VLAN tag for the install network (use "0" for untagged). timeout is the job timeout in minutes (default 60). Returns the submitted job — poll hmc_get_job for status.

Set wait=True to block until the job reaches a terminal state.

Submit a NIM-based LPAR OS installation job.

lpar_uuid is the UUID of an existing (powered-off) LPAR. The LPAR will PXE-boot from the NIM server at nim_ip to install its OS. nim_gateway and nim_subnetmask define the network for the NIM install boot; lpar_ip is the IP address the LPAR uses during the NIM install; vlan_id is the VLAN tag for the install network (use "0" for untagged). timeout is the job timeout in minutes (default 60). Returns the submitted job — poll hmc_get_job for status.

Set wait=True to block until the job reaches a terminal state.

List existing VIOS backups for a given VIOS UUID.

Runs lsviosbackup -id <vios_uuid> on the HMC via SSH and parses the fixed-width table into a list of dicts keyed by the output header (BackupName, Date, Type). Find vios_uuid with hmc_vios.

Create a VIOS backup via the HMC CLI.

Runs chviosbackup -id <vios_uuid> -operation backup -type <backup_type> on the HMC via SSH. vios_uuid is the VIOS UUID (from hmc_vios).

backup_type must be one of:

• vios — full VIOS configuration backup (default)

• viosioconfig — I/O configuration backup

• ssp — Shared Storage Pool (cluster) backup

Returns the raw HMC CLI output. Poll hmc_list_vios_backups to confirm the backup was created.

Restore a VIOS from a named backup via the HMC CLI.

Runs chviosbackup -id <vios_uuid> -operation restore -file <backup_name> on the HMC via SSH. vios_uuid is the VIOS UUID (from hmc_vios); backup_name is the backup file name as listed by hmc_list_vios_backups.

WARNING: Restoring overwrites the current VIOS configuration. Confirm the vios_uuid and backup_name before calling.

Returns the raw HMC CLI output.

List an LPAR's virtual adapters of a given type.

lpar_name_or_uuid: accepts either a PartitionName or a UUID (find it with hmc_lpars). adapter_type is one of: ClientNetworkAdapter, VirtualSCSIClientAdapter, VirtualFibreChannelClientAdapter, VirtualNICDedicated.

Add a Virtual Ethernet (client network) adapter to an LPAR.

lpar_name_or_uuid: accepts either a PartitionName or a UUID (find it with hmc_lpars). port_vlan_id is the PVID / VLAN the adapter connects to (this is how the adapter is attached to a VirtualNetwork — match the network's VLAN ID and vSwitch). slot_number is the virtual slot (auto-assigned if omitted). tagged=True makes it a VLAN-tagged (trunking) adapter; mac_address pins the MAC (otherwise the HMC generates one). Modifying a running LPAR is a DLPAR operation and needs active RMC.

Add a Virtual SCSI client adapter to an LPAR, paired to a VIOS.

lpar_name_or_uuid: accepts either a PartitionName or a UUID (find it with hmc_lpars). vios_partition_id is the integer PartitionID of the serving VIOS (find it with hmc_vios), and vios_slot is that VIOS's server-side virtual SCSI slot number that owns the backing storage. slot_number is the client adapter's virtual slot (auto-assigned if omitted). Storage backing devices (disks / logical volumes) are then mapped to this adapter on the VIOS.

Add a Virtual Fibre Channel (NPIV) client adapter to an LPAR.

lpar_name_or_uuid: accepts either a PartitionName or a UUID (find it with hmc_lpars). vios_partition_id is the integer PartitionID of the serving VIOS and vios_slot is its server-side virtual FC slot number. The HMC generates the WWPNs. Use this for SAN storage via NPIV instead of vSCSI.

Remove a virtual adapter from an LPAR by its UUID.

lpar_name_or_uuid: accepts either a PartitionName or a UUID (find it with hmc_lpars). adapter_type is one of: ClientNetworkAdapter, VirtualSCSIClientAdapter, VirtualFibreChannelClientAdapter, VirtualNICDedicated. Get adapter UUIDs from hmc_list_adapters. Removing an adapter detaches that storage/network from the partition. Returns a confirmation string (immediate delete — no job to poll).

List Volume Groups on a VIOS.

vios_name_or_uuid: accepts either a PartitionName or a UUID (find it with hmc_vios). Each Volume Group shows free space (MiB), the physical volumes backing it and the virtual disks already carved out.

Create a Volume Group on a VIOS from one or more physical volumes.

vios_name_or_uuid: accepts either a PartitionName or a UUID (find it with hmc_vios). physical_volumes is a list of free PV device names (e.g. ['hdisk10']). Use the GetFreePhysicalVolumes job / VIOS 'lspv' to find unused disks. This pools the disks so virtual disks can be carved out for LPARs.

Create a Virtual Disk (logical volume) inside a Volume Group.

vios_name_or_uuid: accepts either a PartitionName or a UUID (find it with hmc_vios). capacity_mb is the size in MiB. The disk becomes backing storage that you then attach to an LPAR with hmc_map_storage_to_lpar (storage_kind 'VirtualDisk'). Find vg_uuid with hmc_list_volume_groups.

Map backing storage to an LPAR via a Virtual SCSI mapping on a VIOS.

vios_name_or_uuid: accepts either a PartitionName or a UUID (find it with hmc_vios). lpar_name_or_uuid: accepts either a PartitionName or a UUID (find it with hmc_lpars). The LPAR must already have a vSCSI adapter paired to this VIOS — see hmc_add_vscsi_adapter. storage_kind is 'VirtualDisk' (a logical volume created with hmc_create_virtual_disk) or 'PhysicalVolume' (a whole hdisk). storage_name is the DiskName / device name. target_device optionally pins the vtscsi device name on the VIOS.

Create the Virtual Media Repository (named VMLibrary) on a Volume Group.

vios_name_or_uuid: accepts either a PartitionName or a UUID (find it with hmc_vios). The repository holds file-backed ISO images for client partitions; only one can exist per VIOS. size_mb is RepositorySize.

Create a blank VirtualOpticalMedia (ISO container) in the media repository.

vios_name_or_uuid: accepts either a PartitionName or a UUID (find it with hmc_vios). Only blank media can be created via the API; media_name is the file name (e.g. 'aix.iso'), size_mb is MediaSize.

Delete the Virtual Media Repository from a Volume Group.

vios_name_or_uuid: accepts either a PartitionName or a UUID (find it with hmc_vios). This is an immediate (synchronous) delete — it returns a confirmation string once the HMC has applied the change; there is no job to poll.

List Clusters (sets of VIOS nodes sharing a storage pool).

List Shared Storage Pools or get one by UUID.

When ssp_uuid is omitted, returns a list of all Shared Storage Pools (capacity, free space, logical units).

When ssp_uuid is provided, returns the full details dict for that one pool (physical volumes, logical units), or None if not found.

Create a Logical Unit (file-backed disk) in a Cluster/SSP.

Submits a CreateLogicalUnit job and returns it — poll hmc_get_job for status; the result holds the new LU's UDID in LUCreated. lu_type is THIN or THICK; device_type is VirtualIO_Disk or VirtualIO_Image. cloned_from is an optional source LU UDID to clone. Find cluster_uuid with hmc_list_clusters.

Set wait=True to block until the job reaches a terminal state.

Delete a Logical Unit from a Cluster/SSP by its UDID.

Submits a DeleteLogicalUnit job and returns it — poll hmc_get_job for status (an asynchronous delete, unlike the immediate delete tools).

Set wait=True to block until the job reaches a terminal state.

List VirtualSwitches on a managed system (names, SwitchIDs, mode).

system_name_or_uuid: accepts either a SystemName or a UUID (find it with hmc_systems). The SwitchID is what hmc_create_virtual_network and hmc_add_network_adapter reference.

List Virtual Networks (VLANs) on a managed system.

system_name_or_uuid: accepts either a SystemName or a UUID (find it with hmc_systems).

Create a Virtual Network (VLAN) on a managed system.

system_name_or_uuid: accepts either a SystemName or a UUID (find it with hmc_systems). vswitch_id is the numeric SwitchID of the backing VirtualSwitch (see hmc_list_virtual_switches). tagged sets whether bridged traffic keeps the VLAN tag.

Delete a Virtual Network from a managed system.

system_name_or_uuid: accepts either a SystemName or a UUID (find it with hmc_systems). Note: a network referenced by a NetworkBridge, or equal to a trunk adapter's PVID, cannot be deleted until the bridge is removed. Returns a confirmation string (immediate delete — no job to poll).

List NetworkBridges (Shared Ethernet Adapters) on a managed system.

system_name_or_uuid: accepts either a SystemName or a UUID (find it with hmc_systems).

List Virtual Fibre Channel (NPIV) adapters for a managed system via the HMC CLI.

Runs lshwres -r virtualio --rsubtype fc --level lpar -m <system_name> on the HMC via SSH and returns parsed dicts with fields including lpar_name, slot_num, wwpns, and remote_lpar_id.

The system and partition may be given by CLI name or by UUID; UUIDs are resolved to their CLI names via REST (falling back to an lssyscfg lookup over SSH when the REST API is unreachable) before the command runs. Pass lpar_name_or_uuid to restrict results to a single partition. Either a CLI name or UUID works; use hmc_systems to find a system UUID and hmc_lpars to find an LPAR UUID.

List Shared Ethernet Adapter (SEA) virtual Ethernet ports via the HMC CLI.

Runs lshwres -r virtualio --rsubtype eth --level lpar -m <system_name> -F lpar_name,port_vlan_id,vswitch,state,trunk_priority on the HMC via SSH and returns parsed dicts with those five fields.

The system and partition may be given by CLI name or by UUID; UUIDs are resolved to their CLI names via REST (falling back to an lssyscfg lookup over SSH when the REST API is unreachable) before the command runs. Pass lpar_name_or_uuid to restrict results to a single partition. Either a CLI name or UUID works; use hmc_systems to find a system UUID and hmc_lpars to find an LPAR UUID.

Toggle a physical SR-IOV adapter between SR-IOV and dedicated mode.

Runs chhwres -r sriov -m <system_name> -o s --id <adapter_id> -a "sriov_adapter_mode=<mode>" on the HMC via SSH and returns the raw command output.

The system may be given by CLI name or by UUID; a UUID is resolved to its CLI name via REST (falling back to an lssyscfg lookup over SSH when the REST API is unreachable) before the command runs.

adapter_id is the physical adapter identifier as reported by hmc_list_io_slots.

mode must be one of:

• "sriov" — enable SR-IOV mode (shared virtual functions)

• "dedicated" — disable SR-IOV, use as a dedicated (passthrough) adapter

WARNING: Changing SR-IOV adapter mode affects all partitions using virtual functions on that adapter. Confirm system_name_or_uuid and adapter_id before calling.

List vNICs (SR-IOV-backed Virtual NICs) on an LPAR via the HMC CLI.

Runs lshwres -r virtualio --rsubtype vnic --level lpar -m <system_name> --filter lpar_names=<lpar_name> on the HMC via SSH and returns one dict per vNIC with fields such as vnic_id, capacity, vswitch_name, port_vlan_id, and backing_devices.

The system and partition may be given by CLI name or by UUID; UUIDs are resolved to their CLI names via REST (falling back to an lssyscfg lookup over SSH when the REST API is unreachable) before the command runs. Use hmc_systems to find a system UUID and hmc_lpars to find an LPAR UUID.

Add a vNIC (SR-IOV-backed Virtual NIC) to an LPAR via the HMC CLI.

Runs chhwres -r virtualio --rsubtype vnic -o a -m <system_name> --filter lpar_names=<lpar_name> -a "<attrs>" on the HMC via SSH.

The system and partition may be given by CLI name or by UUID; UUIDs are resolved to their CLI names via REST (falling back to an lssyscfg lookup over SSH when the REST API is unreachable) before the command runs.

V1 scope boundary: Only the following parameters are supported in this version: capacity, vswitch_name, port_vlan_id, and backing_devices (optional, opaque string passed verbatim). Complex backing-device topology (multi-adapter failover, per-device SR-IOV physical port IDs, capacity weights) is a follow-up and explicitly out of scope for v1.

Returns the raw HMC command output on success.

WARNING: This modifies the LPAR configuration on the HMC. Confirm system_name_or_uuid, lpar_name_or_uuid, and vswitch_name before calling. The underlying physical adapter must be in SR-IOV mode (see hmc_set_sriov_adapter_mode).

Raises: HMCCLIError: If the HMC command fails, e.g. because the underlying SR-IOV adapter is not in SR-IOV mode.

Remove a vNIC from an LPAR via the HMC CLI.

Runs chhwres -r virtualio --rsubtype vnic -o r -m <system_name> --filter lpar_names=<lpar_name> -a "vnic_id=<vnic_id>" on the HMC via SSH.

The system and partition may be given by CLI name or by UUID; UUIDs are resolved to their CLI names via REST (falling back to an lssyscfg lookup over SSH when the REST API is unreachable) before the command runs.

vnic_id is the numeric ID as reported by hmc_list_vnics.

WARNING: This modifies the LPAR configuration on the HMC. Confirm system_name_or_uuid, lpar_name_or_uuid, and vnic_id before calling. Returns the HMC CLI output (immediate delete — no job to poll).

Live-migrate (LPM) an LPAR to another managed system.

lpar_name_or_uuid: accepts either a PartitionName or a UUID (find it with hmc_lpars). Submits a Migrate job. target_system is the target managed-system name. Optionally pin the target profile / wait time. Poll hmc_get_job for status. Run hmc_migrate_validate_lpar first to pre-check.

Set wait=True to block until the job reaches COMPLETED / FAILED / EXCEPTION (or until timeout_seconds elapses).

Validate whether an LPM migration of an LPAR to target_system would succeed.

lpar_name_or_uuid: accepts either a PartitionName or a UUID (find it with hmc_lpars). Set wait=True to block until the validation job reaches a terminal state.

Abort an in-progress LPM migration of an LPAR.

lpar_name_or_uuid: accepts either a PartitionName or a UUID (find it with hmc_lpars).

Recover an LPAR after a failed LPM migration.

lpar_name_or_uuid: accepts either a PartitionName or a UUID (find it with hmc_lpars).

Remote-restart a failed LPAR on another managed system.

lpar_name_or_uuid: accepts either a PartitionName or a UUID (find it with hmc_lpars).

List partition templates or get one by UUID.

When template_uuid is omitted, returns a list of all partition templates in the HMC template library.

When template_uuid is provided, returns the full config dict for that one template, or None if not found.

Deploy a partition from a draft partition template.

draft_template_uuid is the transformed/replica template UUID (produced by capture/transform), target_system_uuid is the managed system to create the partition on. Submits a Deploy job; poll hmc_get_job for status.

Set wait=True to block until the job reaches a terminal state.

Get PCM monitoring preferences for a resource.

category is the resource type, e.g. 'ManagedSystem' or 'LogicalPartition'; resource_name_or_uuid is the name or UUID of that resource (a SystemName or UUID from hmc_systems, or a PartitionName or UUID from hmc_lpars). Returns flags like LongTermMonitorEnabled, AggregationEnabled, ShortTermMonitorEnabled, ComputeLTMEnabled, EnergyMonitorEnabled.

Enable/disable PCM data collection for a resource.

category is the resource type, e.g. 'ManagedSystem' or 'LogicalPartition'; resource_name_or_uuid is the name or UUID of that resource. Only the flags you set are changed. Turning on aggregation implicitly enables long-term monitoring on the HMC. Long-term + aggregation are required before processed/aggregated metrics become available. Returns the updated preferences dict ({} if the HMC returns no body).

Raises: ValueError: if no preference flags are supplied.

List or download processed PCM metrics JSON documents.

category is the resource type, e.g. 'ManagedSystem' or 'LogicalPartition'; resource_name_or_uuid is the name or UUID of that resource. Processed metrics have 30s granularity and ~2h retention. Timestamps are ISO-8601 UTC (yyyy-MM-ddTHH:mm:ssZ); start_ts is required.

mode='links' returns the Atom feed link list (list of dicts with 'link', 'updated', 'title' keys). mode='fetch' (default) downloads and returns the parsed JSON of the most recent document, or {} when no metrics are available in the requested range.

List or download aggregated PCM metrics JSON documents.

category is the resource type, e.g. 'ManagedSystem' or 'LogicalPartition'; resource_name_or_uuid is the name or UUID of that resource. Aggregated metrics are the long-term rollup used for trend analysis. Timestamps are ISO-8601 UTC (yyyy-MM-ddTHH:mm:ssZ); start_ts is required.

mode='links' returns the Atom feed link list. mode='fetch' (default) downloads and returns the parsed JSON of the most recent document, or {} when no metrics are available in the requested range. Requires aggregation to be enabled in PCM preferences.

List HMC user accounts or get one by username.

When name is provided, returns a single resource dict for that user, or None if not found. user_type is ignored when name is supplied.

When name is omitted, returns a list of all user accounts filtered by user_type: 'local' (local HMC accounts), 'kerberos' (Kerberos/LDAP-backed accounts), or 'all' (default). Returns one dict per user: {UUID, title, link, ResourceType, Resource} where Resource holds the flattened HmcUser fields.

Create a new HMC local user account.

name is the login username. taskrole controls what the user can do (e.g. 'hmcoperator', 'hmcviewer', 'hmcsuperadmin'). password is the initial password. description is optional. pwage is the password expiration in days (0 = never expires). This creates a real account — confirm the taskrole before calling. Returns the created user resource dict.

Modify an existing HMC user account.

Only the fields you supply are changed. enable=True re-enables a disabled account; enable=False disables it. Use hmc_users(name=...) to confirm the current state before calling. Returns the updated user resource dict.

Delete an HMC user account by username.

This permanently removes the account — it is irreversible. Confirm the username with hmc_users(name=...) before calling. Returns a confirmation string (immediate delete — no job to poll).

List HMC password policies.

policy_type selects what to return: 'policies' (default) returns the list of defined password policies, 'status' returns activation status. Returns one dict per policy: {UUID, title, link, ResourceType, Resource}.

Create a new HMC password policy.

policy_name is the unique name for the policy. pwage is the maximum password age in days (0 = never expires). min_length is the minimum password length. min_digits, min_uppercase, min_lowercase, and min_special set character-class minimums. hist_size controls how many previous passwords cannot be reused. warn_pwage is the number of days before expiry to warn the user. min_pwage is the minimum days before a password may be changed. Confirm the policy_name before calling. Returns the created policy resource dict.

Modify an existing HMC password policy.

Only the fields you supply are changed. Use hmc_list_password_policies to confirm the current state before calling. To activate or deactivate a policy, use the HMC console — the REST API activates a policy by name via the PolicyType=status query path rather than a direct field change. Returns the updated policy resource dict.

Delete an HMC password policy by name.

This permanently removes the policy — it is irreversible. Confirm the policy_name with hmc_list_password_policies before calling. Returns a confirmation string (immediate delete — no job to poll).

Get the current HMC LDAP server configuration.

Returns a single resource dict describing the configured LDAP server URL, base DN, bind DN, search filter, and HMC group mappings, or None if no LDAP is configured. Equivalent to Ansible hmc_user state=ldap_facts.

Configure the HMC LDAP server integration.

server_url is the LDAP or LDAPS URL (e.g. 'ldap://ldap.example.com' or 'ldaps://ldap.example.com:636'). Only the fields you supply are changed.

base_dn: LDAP search base (e.g. 'dc=example,dc=com'). bind_dn: DN of the account used to bind for searches. bind_pw: password for the bind account. search_filter: LDAP search filter (e.g. '(objectClass=person)'). hmc_groups: comma-separated LDAP groups mapped to HMC access. group_member_attributes: LDAP attribute used for group membership.

Equivalent to Ansible hmc_user action=configure_ldap. Returns the updated LDAP configuration resource dict.

Remove a component of the HMC LDAP server configuration.

resource selects what to remove. Valid values: 'backup' — remove the backup LDAP server 'ldap' — remove the entire LDAP configuration 'binddn' — remove the bind DN 'bindpw' — remove the bind password 'searchfilter' — remove the custom search filter 'hmcgroups' — remove HMC group mappings 'groupmemberattributes' — remove group-member attribute settings

Equivalent to Ansible hmc_user action=remove_ldap_config. Use hmc_get_ldap_config to inspect the current state before calling. Returns a confirmation string (immediate delete — no job to poll).

Submit an HMC software update or upgrade job.

kind='update' installs PTFs (patch level); kind='upgrade' performs a full HMC version upgrade. repository is a dict describing the software source: {"type": "nfs", "host": "repo.example.com", "path": "/images/hmc"} {"type": "sftp", "host": "repo.example.com", "path": "/hmc", "user": "admin", "sftp_pw": "..."} {"type": "disk"} # use files already on the HMC disk

Submits an Update or Upgrade job to ManagementConsole; poll hmc_get_job for status. console_uuid is the ManagementConsole UUID (from hmc_console_info).

Set wait=True to block until the job reaches a terminal state.

Get available PTFs (fixes) for the HMC software.

Issues a GET to the ManagementConsole resource with the SoftwareUpdate group, which returns available PTF information. console_uuid is the ManagementConsole UUID (from hmc_console_info). Does not submit a job.

Submit a VIOS software update or upgrade job.

vios_name_or_uuid: accepts either a PartitionName or a UUID (find it with hmc_vios). kind='update' installs fixes (PTF level); kind='upgrade' performs a full VIOS version upgrade. repository describes the image source (same format as hmc_hmc_update). Submits an Update or Upgrade job to VirtualIOServer; poll hmc_get_job for status.

Set wait=True to block until the job reaches a terminal state.

Submit a managed system firmware update job.

system_name_or_uuid: accepts either a SystemName or a UUID (find it with hmc_systems). repository describes the firmware image source (same format as hmc_hmc_update). Submits an UpdateFirmware job to ManagedSystem; poll hmc_get_job for status.

Set wait=True to block until the job reaches a terminal state.

Backup all LPAR profiles on a Power system via the HMC CLI.

Runs bkprofdata -m <system_name> -f <file_path> on the HMC via SSH and returns the raw command output.

The system may be given by CLI name or by UUID; a UUID is resolved to its CLI name via REST (falling back to an lssyscfg lookup over SSH when the REST API is unreachable) before the command runs.

IMPORTANT: file_path is on the HMC filesystem, not the local machine. The backup file will be created at that path on the HMC host.

Restore LPAR profiles from a backup file via the HMC CLI.

Runs rstprofdata -m <system_name> -f <file_path> on the HMC via SSH and returns the raw command output.

The system may be given by CLI name or by UUID; a UUID is resolved to its CLI name via REST (falling back to an lssyscfg lookup over SSH when the REST API is unreachable) before the command runs.

IMPORTANT: file_path is on the HMC filesystem, not the local machine. The backup file must already exist at that path on the HMC host.

WARNING: Restoring overwrites the current LPAR profile configuration. Confirm the system_name_or_uuid and file_path before calling.

Sync an LPAR's running configuration back to its current profile.

Runs chsyscfg -r lpar -m <system_name> -i "name=<lpar_name>,sync_curr_profile=1" on the HMC via SSH and returns the raw command output.

This operation saves the LPAR's current running configuration to its current named profile, overwriting the previous profile definition.

WARNING: Overwrites the current profile definition. Confirm the system_name_or_uuid and lpar_name_or_uuid before calling.

The system and partition may be given by CLI name or by UUID; UUIDs are resolved to their CLI names via REST (falling back to an lssyscfg lookup over SSH when the REST API is unreachable) before the command runs.

Add a physical I/O slot DRC index to an LPAR's profile.

Runs chsyscfg -r prof -m <system_name> -i "name=<profile_name>,io_slots+=<drc_index>//0,lpar_name=<lpar_name>" --force on the HMC via SSH and returns the raw command output.

This operation appends the specified physical I/O slot to the profile's I/O slot list. Use --force to override any conflicts.

The system and partition may be given by CLI name or by UUID; UUIDs are resolved to their CLI names via REST (falling back to an lssyscfg lookup over SSH when the REST API is unreachable) before the command runs.

Get the description field of an LPAR via the HMC CLI.

Runs lssyscfg -r lpar -m <system_name> --filter lpar_names=<lpar_name> -F description on the HMC via SSH and returns the raw output (the description string, or an empty line if none is set).

This field is not available via the HMC REST API; it is the same description visible in the HMC GUI Partitions tab.

The system and partition may be given by CLI name or by UUID; UUIDs are resolved to their CLI names via REST (falling back to an lssyscfg lookup over SSH when the REST API is unreachable) before the command runs.

Set the description field of an LPAR via the HMC CLI.

Runs chsyscfg -r lpar -m <system_name> -i "name=<lpar_name>,description=<description>" on the HMC via SSH.

This field is not settable via the HMC REST API. The description appears in the HMC GUI Partitions tab and is useful for recording partition ownership, purpose, or current task.

The system and partition may be given by CLI name or by UUID; UUIDs are resolved to their CLI names via REST (falling back to an lssyscfg lookup over SSH when the REST API is unreachable) before the command runs.

WARNING: This modifies the LPAR configuration on the HMC. Confirm lpar_name_or_uuid and system_name_or_uuid before calling.

Get the MSP (Migratable Service Partition) flag of an LPAR via the HMC CLI.

Runs lssyscfg -r lpar -m <system_name> --filter lpar_names=<lpar_name> -F msp on the HMC via SSH and returns True if the flag is 1, False if 0.

The system and partition may be given by CLI name or by UUID; UUIDs are resolved to their CLI names via REST (falling back to an lssyscfg lookup over SSH when the REST API is unreachable) before the command runs.

Set the MSP (Migratable Service Partition) flag of an LPAR via the HMC CLI.

Runs chsyscfg -r lpar -m <system_name> -i "name=<lpar_name>,msp=<0|1>" on the HMC via SSH.

The system and partition may be given by CLI name or by UUID; UUIDs are resolved to their CLI names via REST (falling back to an lssyscfg lookup over SSH when the REST API is unreachable) before the command runs.

WARNING: This modifies the LPAR configuration on the HMC. Confirm lpar_name_or_uuid and system_name_or_uuid before calling.

Get processor compatibility modes supported by a managed system.

Runs lssyscfg -r sys -m <system_name> -F lpar_proc_compat_modes on the HMC via SSH and returns a list of supported mode strings.

The system may be given by CLI name or by UUID; a UUID is resolved to its CLI name via REST (falling back to an lssyscfg lookup over SSH when the REST API is unreachable) before the command runs.

Get the current and pending processor compatibility modes for an LPAR.

Runs lssyscfg -r lpar -m <system_name> --filter lpar_names=<lpar_name> -F pend_lpar_proc_compat_mode,curr_lpar_proc_compat_mode on the HMC via SSH.

The system and partition may be given by CLI name or by UUID; UUIDs are resolved to their CLI names via REST (falling back to an lssyscfg lookup over SSH when the REST API is unreachable) before the command runs.

Returns a dict with keys "pend" and "curr".

Set the processor compatibility mode of an LPAR.

Runs chsyscfg -r lpar -m <system_name> -i "name=<lpar_name>,lpar_proc_compat_mode=<mode>" on the HMC via SSH.

The system and partition may be given by CLI name or by UUID; UUIDs are resolved to their CLI names via REST (falling back to an lssyscfg lookup over SSH when the REST API is unreachable) before the command runs.

WARNING: This modifies the LPAR configuration on the HMC. Confirm lpar_name_or_uuid, system_name_or_uuid, and mode before calling.

List physical I/O slots on a managed system via the HMC CLI.

Runs lshwres -r io --rsubtype slot -m <system_name> on the HMC via SSH and returns one dict per slot. Each dict includes fields such as drc_name, pci_class, feature_codes, and lpar_name (empty string when the slot is unassigned).

The system may be given by CLI name or by UUID; a UUID is resolved to its CLI name via REST (falling back to an lssyscfg lookup over SSH when the REST API is unreachable) before the command runs.

pci_class filters by PCI class:

• "all" — return every slot (default)

• "eth" — Ethernet adapters (PCI class 0200)

• "sas" — SAS/SCSI adapters (PCI class 0104)

• "san" — Fibre Channel / SAN adapters (PCI class 0C04)

• "nvme" — NVMe adapters (PCI class 0108)

List shared memory pools on a managed system via the HMC CLI.

Runs lshwres -r mempool -m <system_name> on the HMC via SSH and returns one dict per pool with fields such as pool_name, size, lpar_names, and curr_lpar_names (comma-separated).

The system may be given by CLI name or by UUID; a UUID is resolved to its CLI name via REST (falling back to an lssyscfg lookup over SSH when the REST API is unreachable) before the command runs.

Remove a shared memory pool from a managed system via the HMC CLI.

Before issuing the remove command, fetches the current pool list and checks that pool_name exists and that no LPARs are still assigned to it. If a pool with that name is missing, or any LPARs are still assigned, the command is not executed and an HMCCLIError describing the problem is raised instead.

Runs chhwres -r mempool -m <system_name> -o r -a <pool_name> on the HMC via SSH when the pool exists and no LPARs are assigned.

The system may be given by CLI name or by UUID; a UUID is resolved to its CLI name via REST (falling back to an lssyscfg lookup over SSH when the REST API is unreachable) before the command runs.

WARNING: This permanently removes the pool — confirm system_name_or_uuid and pool_name before calling. Returns the HMC CLI output (immediate delete — no job to poll).

Raises: HMCCLIError: If pool_name has LPARs still assigned to it, or if no pool with that name exists on the managed system.

One-call LPAR summary: state, RMC, memory/CPU, OS, adapter count, description.

Composes data from three HMC endpoints in a single call:

1. GET /rest/api/uom/LogicalPartition/{uuid} — main partition data (state, memory, CPU, OS version, partition type / ID).

2. GET /rest/api/uom/LogicalPartition/{uuid}/ClientNetworkAdapter — client network adapters attached to the partition (count returned).

Accepts either a PartitionName (exact match) or a UUID.

Returns a flat summary dict with the most useful fields:

• state / rmc_state — current PartitionState and RMC status.

• current_memory_mb / desired_memory_mb — active and profile memory.

• current_proc_units / desired_proc_units — active and profile CPU.

• desired_vcpus / dedicated_procs — virtual processors or dedicated CPUs.

• os_version / os_type — OS details reported by the HMC.

• client_network_adapter_count — number of client network adapters.

• description — partition description if set.

• mapped_storage — always null; resolving vSCSI-mapped storage requires a VIOS UUID hop (vSCSI adapter → vios_partition_id → list_vios + PartitionID match → get_vios_storage_detail) and is out of scope for this best-effort summary. Use hmc_vios for per-VIOS storage mappings.

Raises ValueError when the partition cannot be found.

One-call managed system summary: state, MTMS, firmware, LPAR counts, free resources, VIOS count.

Composes data from three HMC endpoints in a single call:

1. GET /rest/api/uom/ManagedSystem/{uuid} — main system data (state, MTMS, firmware version, total memory/CPU).

2. GET /rest/api/uom/ManagedSystem/{uuid}/LogicalPartition — LPAR list, counted by PartitionState.

3. GET /rest/api/uom/ManagedSystem/{uuid}/VirtualIOServer — VIOS count.

Accepts either a SystemName (exact match) or a UUID.

Returns a flat summary dict with the most useful fields:

• state — current system State (operating, standby, ...).

• mtms — machine type/model/serial (MachineTypeModelSerialNumber).

• firmware_version — system firmware version string.

• total_memory_mb / free_memory_mb — total assignable and free memory.

• total_proc_units / free_proc_units — total configurable and free CPU.

• lpar_count — total number of LPARs.

• lpar_states — dict mapping PartitionState → count.

• vios_count — number of Virtual I/O Servers.

Raises ValueError when the system cannot be found.