Update NIC Properties
The Update NIC Properties operation updates the properties of a single NIC object that is designated by its element ID and the object ID of the owning partition. For a Partition on a CPC with API feature dpm-hipersockets-partition-link-management available, this operation should not be used for NICs of type "iqd" because such NICs are managed via Partition Links of type hipersockets. Therefore, updating the properties of such a NIC object should be done by sending a corresponding request to the Modify Partition Link operation. [Updated by feature dpm-hipersockets-partition-link-management]
HTTP method and URI
POST /api/partitions/{partition-id}/nics/{nic-id}URI variables:
| Name | Type | Description |
|---|---|---|
| {partition-id} | String | Object ID of the Partition object. |
| {nic-id} | String | Element ID of the NIC. |
Request body contents
The request body is expected to contain one or more field names representing writable NIC properties, along with the new values for those fields.
The request body can and should omit fields for properties whose values are not to be changed by this operation. Properties for which no input value is provided remain unchanged by this operation.
Description
This operation modifies the NIC properties for the NIC specified by the request URI.
A 404 (Not Found) status code is returned if the request URI does not designate an existing NIC element of an existing partition, or if the API user does not have object-access permission to that partition.
If this operation changes the value of any property for which property-change notifications are due, those notifications are issued asynchronously to this operation.
If the API user doesn't have action/task permission to the Partition Details task, 403 (Forbidden) status code is returned. If the partition is in one of the transitional states ("starting" or "stopping"), or if the CPC is not in a valid state, a 409 (Conflict) status code is returned.
Authorization requirements
- Object-access permission to the Partition object designated by {partition-id}.
- Object-access permission to the owning Partition Link object when the NIC element designated by {nic-id} is of type "iqd" and the Partition exists on a CPC with API feature dpm-hipersockets-partition-link-management available. [Updated by feature dpm-hipersockets-partition-link-management]
- Action/task permission to the Partition Details task.
- Action/task permission to the Partition Link Details task when the NIC element designated by {nic-id} is of type "iqd" and the Partition exists on a CPC with API feature dpm-hipersockets-partition-link-management available. [Updated by feature dpm-hipersockets-partition-link-management]
- When updating network-adapter-port-uri, object-access permission to the adapter identified in that URI.
- When updating virtual-switch-uri, object-access permission to the backing Adapter object of the Virtual Switch object identified in that URI.
HTTP status and reason codes
On success, HTTP status code 204 (No Content) is returned and no response body is provided.
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.
| 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. |
| 5 | For partitions that are not of type
"ssc":
|
|
| 7 | The locally administered bit in the value specified for the mac-address property is invalid. or the ssc-management-nic was set to true, but the type of the NIC element is not "iqd" or "osd". | |
| 8 | For NIC elements of type
"roce" or "cna", the NIC name provided by the user is already in
use by another NIC of the partition, or the provided device-number is already in use by an instance of one of the objects listed in PCI-based device numbers of the partition. For NIC elements of type "iqd" or "osd", the NIC name provided by the user is already in use by another NIC of the partition, or the provided device-number is already in use by an instance of one of the objects listed in Channel-based device numbers, or the mac-address provided by the user is already in use by another NIC in any of the partitions in the CPC. |
|
| 15 | ssc-management-nic was set to true,
but no value for ssc-ip-address-type was
provided. ssc-ip-address-type was set to "ipv4" or "ipv6", but no value for ssc-ip-address or ssc-mask-prefix was provided. For partitions that are not
of type
"ssc":
|
|
| 18 | For partitions of type
"ssc":
For partitions of other types:
|
|
| 19 | For NIC elements of type "iqd" on a Partition on a CPC with API feature dpm-hipersockets-partition-link-management available, the virtual-switch-uri property is not writable. [Updated by feature dpm-hipersockets-partition-link-management] | |
| 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 {partition-id} does not designated an existing Partition object, or the API user does not have object-access permission to it. |
| 2 | The object ID in the Network Port URI in request body field network-adapter-port-uri does not designate an existing Adapter object, or the API user does not have object-access permission to that adapter, or the object ID in the virtual switch URI in request body field virtual-switch-uri does not designate an existing Virtual Switch object, or the API user does not have object-access permission to that virtual switch. |
|
| 5 | The request URI does not designate an existing NIC of an existing partition. | |
| 6 | The element ID in the Network Port URI in request body field network-adapter-port-uri does not designate an existing adapter port of the adapter. |
|
| 409 (Conflict) | 1 | Partition status is not valid to perform the operation. |
| 2 | Partition object with ID {partition-id} was busy and request timed out. | |
| 6 | The state of the CPC hosting the partition is not valid to perform the operation (must be in one of the following states: "active", "service-required", "degraded", or "exceptions".) | |
| 8 | The request cannot be processed because the update to
virtual-switch-uri/network-adapter-port-uri attempts to
change the switch/port type. ssc-management-nic was set to true, but the partition's type is not "ssc". For partitions that are not of
type
"ssc":
|
|
| 10 | The operation cannot be performed because the affected SE is in the process of being shut down. | |
| 18 | For partitions of type
"ssc":
For partitions of other types:
|
|
| 557 | The operation failed because it requires the generation of one or more MAC addresses, but the range of available addresses has been exhausted. | |
| 503 (Service Unavailable) | 1 | The request could not be processed because the HMC is not currently communicating with an SE needed to perform the requested operation. |
As outlined above, when updating the properties of a NIC of type "iqd" owned by a Partition on a CPC with API feature dpm-hipersockets-partition-link-management available, a corresponding Modify Partition Link operation is performed. Certain HTTP status and reason codes are reported from both operations, therefore it is recommended to consult the response body details in case of failures. [Updated by feature dpm-hipersockets-partition-link-management]
Additional standard status and reason codes can be returned, as described in Invoking API operations.
Example HTTP interaction
POST /api/partitions/b4c4bf9e-97e0-11e5-9d1f-020000000192/nics/eb6887e4-97e8-11e5-9d1f-
020000000192 HTTP/1.1
x-api-session: 3nho0b70bohx2ei3wjryvayxgxxnqo7wtqyj3lsifu4kfok2nf
content-type: application/json
content-length: 25
{
"name":"NicUpdateName"
}204 No Content
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Tue, 01 Dec 2015 05:17:57 GMT
<No response body>