Create NIC

Edit online

The Create NIC operation creates a NIC for the partition with the given identifier. 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, creating such a NIC object should be done by sending a corresponding request to the Modify Partition Link or Create Partition Link operation. It is recommended to use the Create partition Link operation as it can create the HiperSockets adapter and the NIC in the same call. [Updated by feature dpm-hipersockets-partition-link-management]

HTTP method and URI

POST /api/partitions/{partition-id}/nics

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

Request body contents

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

Field name	Type	Rqd/Opt	Description
`name`	String (1-64)	Required	The value to be set as the NIC's name property.
`description`	String (0-1024)	Optional	The value to be set as the NIC's description property.
`network-adapter-port-uri`	String/ URI	Required, if the adapter type is "roce" or "cna"	The value to be set as the NIC's network-adapter-port-uri property. Required if the type of the adapter containing the port referenced by the network-adapter-port-uri field is "roce" or "cna".
`virtual-switch-uri`	String/ URI	Required, if the adapter type is "osd" or "hipersockets"	The value to be set as the NIC's virtual-switch-uri property. Required if the type of the adapter containing the port referenced by the virtual-switch-uri field is "osd" or "hipersockets".
`device-number`	String (4)	Optional	The value to be set as the NIC's device-number property. Device number for this NIC. If not provided, a device-number is auto-generated.
`ssc-management-nic`	Boolean	Optional	The value to be set as the NIC's ssc-management-nic property. Cannot be set to true when the partition's type is not "ssc" or the type of the adapter referenced by the network-adapter-port-uri is "roce" or "cna". Default: false
`function-number`	Integer	Optional	The value to be set as the NIC's function-number property.
`function-range`	Integer (1-128)	Optional	The value to set as the NIC's function-range property.
`ssc-ip-address-type`	String Enum	Required if ssc-management-nic is true	The value to be set as the NIC's ssc-ip-address-type property. Cannot be set when the partition's type is not "ssc".
`ssc-ip-address`	String/ IPv4 Address or String/ IPv6 Address	Required if ssc-ip-address-type is "ipv4" or "ipv6"	The value to be set as the NIC's ssc-ip-address property. Cannot be set when the partition's type is not "ssc".
`vlan-id`	Integer	Optional	The value to be set as the NIC's vlan-id property.
`ssc-mask-prefix`	String	Required if ssc-ip-address-type is "ipv4" or "ipv6"	The value to be set as the NIC's ssc-mask-prefix. Cannot be set when the partition's type is not "ssc".
`mac-address`	String	Optional	The value to be set as the NIC's mac-address property.
`vlan-type`	String Enum	Required if vlan-id is provided	The value to be set as the NIC's vlan-type property.

Response body contents

On successful completion, the response body contains the URI of the created NIC object.

Field name	Type	Description
`element-uri`	String/ URI	The element-uri property of the created NIC object.

Description

This operation creates a NIC for the identified partition and then returns the URI of the created object. Upon success, the response includes a Location header that provides the URI of the created NIC object. An Inventory Change notification is emitted asynchronously to this operation. The request identifies the NIC's backing adapter by specifying either a network port URI or a virtual switch URI.

If this operation changes the value of any property for which property-change notifications are due, those notifications are issued asynchronously to this operation.

A 404 (Not Found) status code is returned if the object-id in the URI {partition-id} does not designate an existing Partition object, or the API user does not have object-access permission to it. If the API user doesn't have action/task permission to 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.

To create a NIC of type "iqd" for a Partition on a CPC with API feature dpm-hipersockets-partition-link-management available, using the Modify Partition Link operation is preferred over Create NIC, because such NICs are managed via Partition Links. Although Modify Partition Link is preferred in this scenario, the Create NIC operation can still be used to create new NICs with type "iqd" owned by a Partition on a CPC with API feature dpm-hipersockets-partition-link-management available. In that case the HMC essentially converts the Create NIC operation into a corresponding Modify Partition Link operation and processes it in a synchronous fashion. The changes in the underlying implementation are transparent to the user for successful invocations of the operation. In case of failures, see Table 7 for more information. [Updated by feature dpm-hipersockets-partition-link-management]

Authorization requirements

This operation has the following 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]

HTTP status and reason codes

On success, HTTP status code 201 (Created) is returned and the response body is provided as described in Response body contents.

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.

Table 1. Create NIC: HTTP status and reason codes
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": The user specified a valid value for the vlan-id property, but did not specify a value for the vlan-type property or it was null. The user did not specify a value for the vlan-id property, but specified the value for the vlan-type property as "enforced".
	7	The locally administered bit in the value specified for the mac-address property is invalid or the ssc-management-nic property 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": The user specified a valid value for the vlan-id property, but vlan-type was null. The user specified the value for the vlan-id property as null, but specified the value of the vlan-type property as "enforced".
	18	For partitions of type "ssc": A non-null value was specified for the vlan-type property. A value for the mac-address property was specified for the NIC element of type "roce" or "cna". For partitions of other types: A value for the properties mac-address, vlan-id, or vlan-type was specified for the NIC element of type "roce" or "cna".
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 designate 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 the 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.
	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 property ssc-management-nic was set to true, but the partition's type is not "ssc" or a function-number for a virtual function was provided, but no physical function was defined yet (on the adapter designated by network-adapter-port-uri).
	10	The operation cannot be performed because the affected SE is in the process of being shut down.
	116	The partition does not have sufficient resources to perform this operation.
	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 creating a NIC of type "iqd" for 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

Figure 1. Create NIC: Request

POST /api/partitions/b4c4bf9e-97e0-11e5-9d1f-020000000192/nics HTTP/1.1
x-api-session: 35yero3ati5fholesprwebpbn3ktukx59cucm4tt4c86m6n9id
content-type: application/json
content-length: 100
{
   "name":"Nic1",
   "virtual-switch-uri":"/api/virtual-switches/0c797342-9750-11e5-bfaa-020000000192"
}

Figure 2. Create NIC: Response

201 Created
server: zSeries management console API web server / 2.0
location: /api/partitions/b4c4bf9e-97e0-11e5-9d1f-020000000192/nics/eb6887e4-97e8-11e5-9d1f-
   020000000192
cache-control: no-cache
date: Tue, 01 Dec 2015 05:03:57 GMT
content-type: application/json;charset=UTF-8
content-length: 123
{
   "element-uri":"/api/partitions/b4c4bf9e-97e0-11e5-9d1f-020000000192/nics/eb6887e4-
      97e8-11e5-9d1f-020000000192"
}