Import DPM Configuration

The Import DPM Configuration operation imports DPM objects such as partitions, NICs, HBAs, virtual functions, and their properties. It also restores DPM-specific CPC properties, like the description, auto-start partition list and capacity groups.

HTTP method and URI

POST /api/cpcs/{cpc-id}/operations/import-dpm-config

In this request, the URI variable {cpc-id} is the object ID of the CPC.

Request body contents

The request body is expected to contain a JSON object with the following fields:

Field name Type Rqd/Opt Description
cpc-properties cpc-info object Optional

An object containing the names of CPC properties and the values to which each of those properties is to be set. This is a very limited set of CPC properties relevant to CPCs enabled for DPM mode.

se-version String (1-8) Required The internal code release level of the primary SE on the machine from which the configuration was exported.
available-features-list Array of cpc-feature-info objects Required The list of optional features or behaviors supported by the CPC on the machine from which the configuration was exported. If the CPC has no optional features, then the array must be empty.
available-api-features-list Array of String Optional The API features available on the source system, as returned by the List CPC API Features operation, issued when the configuration information was exported.
preserve-uris Boolean Optional Controls whether object IDs / element IDs are preserved or if new object IDs / element IDs will be generated. Because those IDs are components of URIs, this field controls whether the URIs of imported objects are preserved. This applies to all objects that will be recreated, for example Partitions, HBAs, NICs, Virtual Functions, Capacity Groups, etc.
Note: This does not apply to existing objects, such as Adapters.
Default: false
preserve-wwpns Boolean Optional Controls whether HBA WWPNs are preserved or if new WWPNs will be generated.

Default: false

adapter-mapping Array of adapter-mapping-info objects Optional Array of adapter mapping information objects. Required when the I/O adapter configuration on this machine differs from that of the machine from which the configuration was exported.
partitions Array of objects Required Array of objects containing the properties of the Partitions to be imported. Each element of this array is expected to be the equivalent of a response body from a Get Partition Properties operation issued when the configuration information was exported.
nics Array of objects Optional Array of objects containing the properties of the NICs to be imported. Each element of this array is expected to be the equivalent of a response body from a Get NIC Properties operation issued when the configuration information was exported.
hbas Array of objects Optional Array of objects containing the properties of the HBAs to be imported. Each element of this array is expected to be the equivalent of a response body from a Get HBA Properties operation issued when the configuration information was exported.
virtual-functions Array of objects Optional Array of objects containing the properties of the Virtual Functions to be imported. Each element of this array is expected to be the equivalent of a response body from a Get Virtual Function Properties operation issued when the configuration information was exported.
adapters Array of objects Required Array of objects containing the properties of the Adapters in the exported configuration. Each element of this array is expected to be the equivalent of a response body from a Get Adapter Properties operation issued when the configuration information was exported. This will not recreate any Adapters; it is used for internal purposes only.
virtual-switches Array of objects Optional Array of objects containing the properties of the Virtual Switches in the exported configuration. Each element of this array is expected to be the equivalent of a response body from a Get Virtual Switch Properties operation issued when the configuration information was exported. This will not recreate any Virtual Switches; it is used for internal purposes only.
capacity-groups Array of objects Optional Array of objects containing the properties of the Capacity Groups to be imported. Each element of this array is expected to be the equivalent of a response body from a Get Capacity Group Properties operation issued when the configuration information was exported.
storage-sites Array of objects Optional Array of objects containing the properties of the Storage Sites to be imported. Each element of this array is expected to be the equivalent of a response body from a Get Storage Site Properties operation issued when the configuration information was exported.
storage-subsystems Array of objects Optional Array of objects containing the properties of the Storage Subsystems to be imported. Each element of this array is expected to be the equivalent of a response body from a Get Storage Subsystem Properties operation issued when the configuration information was exported.
storage-fabrics Array of objects Optional Array of objects containing the properties of the Storage Fabrics to be imported. Each element of this array is expected to be the equivalent of a response body from a Get Storage Fabric Properties operation issued when the configuration information was exported.
storage-switches Array of objects Optional Array of objects containing the properties of the Storage Switches to be imported. Each element of this array is expected to be the equivalent of a response body from a Get Storage Switch Properties operation issued when the configuration information was exported.
storage-control-units Array of objects Optional Array of objects containing the properties of the Storage Control Units to be imported. Each element of this array is expected to be the equivalent of a response body from a Get Storage Control Unit Properties operation issued when the configuration information was exported.
storage-paths Array of objects Optional Array of objects containing the properties of the Storage Paths to be imported. Each element of this array is expected to be the equivalent of a response body from a Get Storage Path Properties operation issued when the configuration information was exported.
storage-groups Array of objects Optional Array of objects containing the properties of the Storage Groups to be imported. Each element of this array is expected to be the equivalent of a response body from a Get Storage Group Properties operation issued when the configuration information was exported.
storage-volumes Array of objects Optional Array of objects containing the properties of the Storage Volumes to be imported. Each element of this array is expected to be the equivalent of a response body from a Get Storage Volume Properties operation issued when the configuration information was exported.
storage-templates Array of objects Optional Array of objects containing the properties of the Storage Templates to be imported. Each element of this array is expected to be the equivalent of a response body from a Get Storage Template Properties operation issued when the configuration information was exported.
storage-template-volumes Array of objects Optional Array of objects containing the properties of the Storage Template Volumes to be imported. Each element of this array is expected to be the equivalent of a response body from a Get Storage Template Volume Properties operation issued when the configuration information was exported.
virtual-storage-resources Array of objects Optional Array of objects containing the properties of the Virtual Storage Resources to be imported. Each element of this array is expected to be the equivalent of a response body from a Get Virtual Storage Resources Properties operation issued when the configuration information was exported.
storage-ports Array of objects Optional Array of objects containing the properties of the Storage Ports to be imported. Each element of this array is expected to be the equivalent of a response body from a Get Storage Port Properties operation issued when the configuration information was exported.
network-ports Array of objects Optional Array of objects containing the properties of the Network Ports to be imported. Each element of this array is expected to be the equivalent of a response body from a Get Network Port Properties operation issued when the configuration information was exported.
partition-links Array of objects Optional

Array of objects containing the properties of the Partition Links to be imported. Each element of this array is expected to be the equivalent of a response body from a Get Partition Link Properties operation issued when the configuration information was exported.

certificates Array of objects Optional Array of objects containing the properties of the Certificate objects to be imported and possibly assigned to one or more Partitions. Each element of this array is expected to be the equivalent of a response body from a Get Certificate Properties operation enriched with the fields of the corresponding response body from a Get Encoded Certificate operation, both issued when the configuration information was exported.

[Added by feature secure-boot-with-certificates]

The cpc-info nested object contains the following fields:

Table 1. cpc-info nested object
Name Type Description
description String (1-1024) The descriptive text associated with this CPC object
auto-start-list Array of auto-start-entry objects An array of auto-start-entry objects in sequence, each representing a single partition or a group of partitions that are automatically started when this CPC is started. The format of that object is described in the Class specific additional properties.

The adapter-mapping-info nested object contains the following fields:

Table 2. adapter-mapping-info nested object
Name Type Description
new-adapter-id String (3) The hexadecimal value of the adapter ID (PCHID) on this machine
old-adapter-id String (3) The hexadecimal value of the adapter ID (PCHID) on the old machine

Response body contents

On successful completion, the response body contains a JSON object with the following field:

Name Type Description
output Array of output-details objects An array of output-details objects containing detailed information about the parts of the configuration that were not restored.

Each nested output-details info object contains the following fields:

Name Type Description
category String/ Enum One of the following, describing the category of the message:
  • "system-to-switches-not-restored" - Certain storage switches connections could not be restored. The items field contains information describing those connections.
  • "acc-vf-not-restored" - Accelerator virtual functions for certain partitions were not restored. The items field contains the names of those partitions.
  • "partition-id-reset" - The Partition ID (partition-id property) for certain partitions was changed. The items field contains the names of those partitions.
  • "boot-type-reset" - The boot type (boot-device property) for certain partitions was reset from "iso-image" to "none". The items field contains the names of those partitions.
  • "ssc-password-reset" - The password (ssc-master-pw property) for certain SSC partitions was reset. The items field contains the names of those partitions.
  • "boot-password-reset" - The FTP password (boot-ftp-password property) for certain partitions was reset. The items field contains the names of those partitions.
  • "processor-type-not-available" - Certain partitions were not restored because the required processor type is not available. The items field contains the names of those partitions.
  • "virtual-switch-port-changed" - Certain virtual switch ports have been changed to the default port. The items field contains information identifying those ports.
items Array of String Additional details about which resources were modified or not restored. The value of the category field defines the contents of this field.

Description

This operation restores a full DPM configuration with all its artifacts like partitions, HBAs, NICs, Accelerators, and Crypto devices. Unique identifiers like Object IDs and WWPNs are preserved. This task is mainly intended for migrating a DPM configuration from an older machine to a new machine. When migrating configurations between machines of the same generation, you have to ensure consistent feature enablement settings. Migrating from a newer machine generation to an older one is not supported. The operation stops on the first fatal error. Non-fatal errors do not stop the import and provide information about unrestored objects within the response body. The request body may contain the same set of properties as generated by the Get Inventory operation.

Authorization requirements

This operation has the following authorization requirements:
  • Object-access permission to the CPC object designated by {cpc-id}
  • Action/task permission to the Import Dynamic Partition Manager Configuration task.
  • Object-access permission to Secure Boot Certificate objects (only applies when the request body contains one or more secure boot Certificate objects to be assigned to Partitions). [Added by feature secure-boot-with-certificates]
  • Action/task permission for the Import Secure Boot Certificates task (only applies when the request body contains one or more Certificate objects). [Added by feature secure-boot-with-certificates]
  • Action/task permission for the Assign Secure Boot Certificates task (only applies when the request body contains one or more secure boot Certificate objects to be assigned to Partitions). [Added by feature secure-boot-with-certificates]

HTTP status and reason codes

On success, HTTP status code 204 (No Content) is returned and no response body is provided. If not all parts of the configuration could be restored, a 200 (OK) is returned and the response body provides additional details.

The following HTTP status codes are returned for the indicated errors, and the response body is a standard error response body providing the reason code indicated and associated error message.

In contrast to other operations, the following table for HTTP status and reason codes only covers key basic error conditions, as it is not feasible to track all potential error cases when importing a potentially large DPM configuration into a new system (that might already contain DPM configuration objects). In general, any error response that corresponding operations to create/attach configuration elements might emit are possible here.

HTTP error status code Reason code Description
400 (Bad Request) Various Errors were detected during common request validation. See Common request validation reason codes for a list of the possible reason codes.
7 The Firmware Feature enablement of the designated CPC does not support the provided configuration objects. The API features availability on the designated CPC or Console does not support the provided configuration objects.
100 The provided se-version is not supported for the import operation of this CPC
403 (Forbidden) 1 The API user does not have the required permission for this operation.
404 (Not Found) 1 The object ID in the URI {cpc-id} does not designate an existing CPC object, or the API user does not have object-access permission to it.
4 The SE associated with the CPC designated by the request URI is not on the required code level to support this operation.
409 (Conflict) 1 The state of the CPC is not valid to perform the operation (must be in one of the following states: "active", "service-required", "degraded", or "exceptions"
5 The operation cannot be performed because the CPC designated by the URI is not in DPM mode.
8 An object with the same URI as one in the request body already exists.
503 (Service Unavailable) 1 The request could not be processed because the HMC is not communicating with the SE needed to perform the requested operation.

Additional standard status and reason codes can be returned, as described in Invoking API operations.

Example HTTP interaction

Figure 1. Import DPM Configuration: Request (Part 1)
POST /api/cpcs/46a42974-59b1-3574-bade-0d2cc3e2f12c/operations/import-dpm-config HTTP/1.1
x-api-session: 1bj062lh2pj8kjinq9sntoytdimuli2edkwwom7vpw0cntdh8j
content-type: application/json
content-length: 5791
{
   "adapter-mapping":[
      {
         "new-adapter-id":"1dd",
         "old-adapter-id":"100"
      }
   ],
   "adapters":[
      {
         "adapter-family":"hipersockets",
         "adapter-id":"7c0",
         "allowed-capacity":12288,
         "channel-path-id":"09",
         "class":"adapter",
         "configured-capacity":81,
         "description":"",
         "detected-card-type":"hipersockets",
         "maximum-total-capacity":12288,
         "maximum-transmission-unit-size":8,
         "name":"hipersocket",
         "network-port-uris":[
            "/api/adapters/bc5c79e6-354f-11e7-911e-00106f0d81cb/network-ports/0"
         ],
         "object-id":"bc5c79e6-354f-11e7-911e-00106f0d81cb",
         "object-uri":"/api/adapters/bc5c79e6-354f-11e7-911e-00106f0d81cb",
         "parent":"/api/cpcs/f8242e42-c99d-3765-892e-5ddebb74bd2e",
         "physical-channel-status":"operating",
         "port-count":1,
         "state":"online",
         "status":"active",
         "type":"hipersockets",
         "used-capacity":27
      },
Figure 2. Import DPM Configuration: Request (Part 2)
      {
         "adapter-family":"ficon",
         "adapter-id":"100",
         "allowed-capacity":64,
         "card-location":"Z22B-D101-J.01",
         "channel-path-id":"0d",
         "class":"adapter",
         "configured-capacity":10,
         "description":"",
         "detected-card-type":"ficon-express-16s-plus",
         "maximum-total-capacity":254,
         "name":"FCP 0100 Z22B-01",
         "object-id":"a44e2648-0a42-11e7-88d2-00106f0d81cb",
         "object-uri":"/api/adapters/a44e2648-0a42-11e7-88d2-00106f0d81cb",
         "parent":"/api/cpcs/f8242e42-c99d-3765-892e-5ddebb74bd2e",
         "physical-channel-status":"operating",
         "port-count":1,
         "state":"online",
         "status":"active",
         "storage-port-uris":[
            "/api/adapters/a44e2648-0a42-11e7-88d2-00106f0d81cb/storage-ports/0"
         ],
         "type":"fcp",
         "used-capacity":6
      }
   ],
   "available-features-list":[],
   "cpc-properties":{
      "description":"CPC description "
   },
   "hbas":[
      {
         "adapter-port-uri":"/api/adapters/a44e2648-0a42-11e7-88d2-00106f0d81cb/
            storage-ports/0",
         "class":"hba",
         "description":"Systemplatte",
         "device-number":"0150",
         "element-id":"633219d0-5ff6-11e7-92e8-00106f0d81cb",
         "element-uri":"/api/partitions/9d1826c4-5ff3-11e7-b4a6-00106f0d81cb/hbas/
            633219d0-5ff6-11e7-92e8-00106f0d81cb",
         "name":"Bootadapter",
         "parent":"/api/partitions/9d1826c4-5ff3-11e7-b4a6-00106f0d81cb",
         "wwpn":"C05076FFE80006A6"
      }
   ],
Figure 3. Import DPM Configuration: Request (Part 3)

   "nics":[
      {
         "class":"nic",
         "description":"Device fuer die freie Welt.",
         "device-number":"0001",
         "element-id":"5d0caee6-5ff4-11e7-90cf-00106f0d81cb",
         "element-uri":"/api/partitions/9d1826c4-5ff3-11e7-b4a6-00106f0d81cb/nics/
            5d0caee6-5ff4-11e7-90cf-00106f0d81cb",
         "mac-address":"12:34:56:78:9a:bc",
         "name":"Netzwerk_Aussen",
         "parent":"/api/partitions/9d1826c4-5ff3-11e7-b4a6-00106f0d81cb",
         "ssc-ip-address":null,
         "ssc-ip-address-type":null,
         "ssc-management-nic":false,
         "ssc-mask-prefix":null,
         "type":"iqd",
         "virtual-switch-uri":"/api/virtual-switches/bc6d7ce6-354f-11e7-a1a3-
            00106f0d81cb",
         "vlan-id":null,
         "vlan-type":null
      }
   ],
   "partitions":[
      {
         "acceptable-status":[
            "active"
         ],
         "access-basic-counter-set":false,
         "access-basic-sampling":false,
         "access-coprocessor-group-set":false,
         "access-crypto-activity-counter-set":false,
         "access-diagnostic-sampling":false,
         "access-extended-counter-set":false,
         "access-global-performance-data":false,
         "access-problem-state-counter-set":false,
         "auto-start":false,
         "autogenerate-partition-id":true,
         "boot-configuration-selector":0,
         "boot-device":"test-operating-system",
         "boot-ftp-host":null,
         "boot-ftp-insfile":null,
         "boot-ftp-username":null,
Figure 4. Import DPM Configuration: Request (Part 4)

         "boot-iso-image-name":null,
         "boot-iso-ins-file":null,
         "boot-logical-unit-number":"0001000000000000",
         "boot-network-device":null,
         "boot-os-specific-parameters":"",
         "boot-record-lba":"",
         "boot-removable-media":null,
         "boot-removable-media-type":null,
         "boot-storage-device":"/api/partitions/9d1826c4-5ff3-11e7-b4a6-00106f0d81cb/
            hbas/633219d0-5ff6-11e7-92e8-00106f0d81cb",
         "boot-timeout":60,
         "boot-world-wide-port-name":"50050763070306A6",
         "class":"partition",
         "cp-absolute-processor-capping":false,
         "cp-absolute-processor-capping-value":1.0,
         "cp-processing-weight-capped":false,
         "cp-processors":6,
         "crypto-configuration":null,
         "current-cp-processing-weight":1,
         "current-ifl-processing-weight":1,
         "degraded-adapters":[],
         "description":"Ihno legt eine LPAR an.",
         "has-unacceptable-status":true,
         "hba-uris":[
            "/api/partitions/9d1826c4-5ff3-11e7-b4a6-00106f0d81cb/hbas/633219d0-
               5ff6-11e7-92e8-00106f0d81cb"
         ],
Figure 5. Import DPM Configuration: Request (Part 5)
         "ifl-absolute-processor-capping":false,
         "ifl-absolute-processor-capping-value":1.0,
         "ifl-processing-weight-capped":false,
         "ifl-processors":0,
         "initial-cp-processing-weight":100,
         "initial-ifl-processing-weight":100,
         "initial-memory":12288,
         "is-locked":false,
         "maximum-cp-processing-weight":999,
         "maximum-ifl-processing-weight":999,
         "maximum-memory":12288,
         "minimum-cp-processing-weight":1,
         "minimum-ifl-processing-weight":1,
         "name":"SUSE_Test",
         "nic-uris":[
            "/api/partitions/9d1826c4-5ff3-11e7-b4a6-00106f0d81cb/nics/5d0caee6-
               5ff4-11e7-90cf-00106f0d81cb"
         ],
         "object-id":"9d1826c4-5ff3-11e7-b4a6-00106f0d81cb",
         "object-uri":"/api/partitions/9d1826c4-5ff3-11e7-b4a6-00106f0d81cb",
         "os-name":"",
         "os-type":"",
         "os-version":"",
         "parent":"/api/cpcs/f8242e42-c99d-3765-892e-5ddebb74bd2e",
         "partition-id":null,
         "permit-aes-key-import-functions":true,
         "permit-cross-partition-commands":false,
         "permit-des-key-import-functions":true,
         "processor-management-enabled":false,
         "processor-mode":"shared",
         "reserve-resources":false,
         "reserved-memory":0,
         "short-name":"SUSETEST",
         "status":"stopped",
         "threads-per-processor":0,
         "type":"linux",
         "virtual-function-uris":[]
      }
   ],
   "se-version":"2.13.1",
   "virtual-switches":[
      {
         "backing-adapter-uri":"/api/adapters/bc5c79e6-354f-11e7-911e-00106f0d81cb",
         "class":"virtual-switch",
         "description":"",
         "name":"7C0.P0.IQD",
         "object-id":"bc6d7ce6-354f-11e7-a1a3-00106f0d81cb",
         "object-uri":"/api/virtual-switches/bc6d7ce6-354f-11e7-a1a3-00106f0d81cb",
         "parent":"/api/cpcs/f8242e42-c99d-3765-892e-5ddebb74bd2e",
         "port":0,
         "type":"hipersockets"
      }
   ]
}
Figure 6. Import DPM Configuration: Response
204 No Content
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Mon, 11 Jun 2018 10:36:04 GMT

<No response body>

Usage notes

  • There is an open source command line tool called zhmc, available from https://github.com/zhmcclient/zhmccli. This tool can assist with:
    • Creating the input data required for this operation by exporting the configuration of an existing machine
    • Invoking this operation using that previously generated data on a new machine
    Note: When using the tool, ensure to always use the latest version, and to study the corresponding release information and change history.
  • By default, only the SERVICE user ID on the HMC has the required task permission for this operation, and that user ID is not enabled for Web Services APIs by default.
  • By default, object IDs and element IDs are not preserved; instead, new unique IDs are generated when importing the objects. This prevents the possibility of duplicate IDs, which would occur when both the new and old systems are attached to the same HMC after the configuration is imported with this operation. The preserve-uris field can be specified as true to preserve the IDs, which can be helpful for situations that depend on the IDs, such as a network (PXE) boot. But care must be taken to never attach both systems to the same HMC if that option is used during this operation. Doing so may result in unpredictable behavior due to the presence of duplicate IDs.
  • By default, the WWPNs of the HBAs are not preserved; instead, new WWPNs are generated when importing the HBAs. The generated WWPNs will match the I/O serial number of the new machine. If the new machine will have the same I/O serial number as the old machine, then it is appropriate to specify preserve-wwpns as true so that the HBAs are imported with their original WWPNs.
  • The operation restores property settings in certain adapters (for example: the type property for storage adapters). However, it does not restore the crypto-type property for crypto adapters; you need to ensure that the target crypto adapters in the new system are set up to match that type. It is recommended that you manually inspect the crypto-type property for all crypto adapters prior to import, and make any changes that might be needed, using the Manage Adapters task.