Skip to main content

Create a new cluster-scoped or SVM-scoped interface

Contributors
PDFs

POST /network/ip/interfaces

Introduced In: 9.6

Creates a new Cluster-scoped or SVM-scoped interface.

Required properties

  • name - Name of the interface to create.

  • ip or subnet

    • ip.address - IP address for the interface.

    • ip.netmask - IP subnet of the interface.

    • subnet.uuid or subnet.name

  • ipspace.name or ipspace.uuid

    • Required for Cluster-scoped interfaces.

    • Optional for SVM-scoped interfaces.

  • svm.name or svm.uuid

    • Required for an SVM-scoped interface.

    • Invalid for a Cluster-scoped interface.

  • If a LIF in the subnet of the specified IP address does not already exist, a location.home_port, a location.home_node, or a location.broadcast_domain needs to be provided.

  • service_policy

    • for SVM scoped interfaces

      • default-data-files for interfaces carrying file-oriented NAS data traffic

      • default-data-blocks for interfaces carrying block-oriented SAN data traffic

      • default-data-iscsi for interfaces carrying iSCSI data traffic

      • default-management for interfaces carrying SVM management requests

    • for Cluster scoped interfaces

      • default-intercluster for interfaces carrying cluster peering traffic

      • default-management for interfaces carrying system management requests

      • default-route-announce for interfaces carrying BGP peer connections

Default property values

If not specified in POST, the following default property values are assigned:

  • scope

    • svm if svm parameter is specified.

    • cluster if svm parameter is not specified

  • enabled - true

  • location.auto_revert - true

  • service_policy

    • default-data-files if scope is svm

    • default-management if scope is cluster and IPspace is not Cluster

    • default-cluster if scope is cluster and IPspace is Cluster

  • failover - Selects the least restrictive failover policy supported by all the services in the service policy.

  • ddns_enabled

    • true if the interface supports data_nfs or data_cifs services

    • false otherwise

  • fail_if_subnet_conflicts - true

  • network interface create

Parameters

Name Type In Required Description

return_records

boolean

query

False

The default is false. If set to true, the records are returned.

  • Default value:

Request Body

Name Type Description

_links

_links

ddns_enabled

boolean

Indicates whether or not dynamic DNS updates are enabled. Defaults to true if the interface supports "data_nfs" or "data_cifs" services, otherwise false.

dns_zone

string

Fully qualified DNS zone name

enabled

boolean

The administrative state of the interface.

fail_if_subnet_conflicts

boolean

This command fails if the specified IP address falls within the address range of a named subnet. Set this value to false to use the specified IP address and to assign the subnet owning that address to the interface.

ip

ip_info

IP information

ipspace

ipspace

Either the UUID or name must be supplied on POST for cluster-scoped objects.

location

location

Current or home location can be modified. Specifying a port implies a node. Specifying a node allows an appropriate port to be automatically selected. Ports are not valid and not shown for VIP interfaces. For POST, broadcast_domain can be specified alone or with home_node. For PATCH, set is_home to true to revert a LIF back to its home port.

metric

metric

The most recent sample of I/O metrics for the interface.

name

string

Interface name

probe_port

integer

Probe port for Cloud load balancer

rdma_protocols

array[string]

Supported RDMA offload protocols

scope

string

Set to "svm" for interfaces owned by an SVM. Otherwise, set to "cluster".

service_policy

service_policy

services

array[string]

The services associated with the interface.

state

string

The operational state of the interface.

statistics

statistics

The real time I/O statistics for the interface.

subnet

ip_subnet_reference

A named subnet. Either UUID or name can be supplied on input.

svm

svm

Applies only to SVM-scoped objects. Either the UUID or name must be supplied on POST.

uuid

string

The UUID that uniquely identifies the interface.

vip

boolean

True for a VIP interface, whose location is announced via BGP.
Example request 
{
  "_links": {
    "self": {
      "href": "/api/resourcelink"
    }
  },
  "dns_zone": "storage.company.com",
  "ip": {
    "address": "10.10.10.7",
    "family": "string",
    "netmask": "24"
  },
  "ipspace": {
    "_links": {
      "self": {
        "href": "/api/resourcelink"
      }
    },
    "name": "Default",
    "uuid": "1cd8a442-86d1-11e0-ae1c-123478563412"
  },
  "location": {
    "broadcast_domain": {
      "_links": {
        "self": {
          "href": "/api/resourcelink"
        }
      },
      "name": "bd1",
      "uuid": "1cd8a442-86d1-11e0-ae1c-123478563412"
    },
    "failover": "string",
    "home_node": {
      "_links": {
        "self": {
          "href": "/api/resourcelink"
        }
      },
      "name": "node1",
      "uuid": "1cd8a442-86d1-11e0-ae1c-123478563412"
    },
    "home_port": {
      "_links": {
        "self": {
          "href": "/api/resourcelink"
        }
      },
      "name": "e1b",
      "node": {
        "name": "node1"
      },
      "uuid": "1cd8a442-86d1-11e0-ae1c-123478563412"
    },
    "node": {
      "_links": {
        "self": {
          "href": "/api/resourcelink"
        }
      },
      "name": "node1",
      "uuid": "1cd8a442-86d1-11e0-ae1c-123478563412"
    },
    "port": {
      "_links": {
        "self": {
          "href": "/api/resourcelink"
        }
      },
      "name": "e1b",
      "node": {
        "name": "node1"
      },
      "uuid": "1cd8a442-86d1-11e0-ae1c-123478563412"
    }
  },
  "metric": {
    "_links": {
      "self": {
        "href": "/api/resourcelink"
      }
    },
    "duration": "PT15S",
    "status": "ok",
    "throughput": {
      "read": 200,
      "total": 1000,
      "write": 100
    },
    "timestamp": "2017-01-25 06:20:13 -0500"
  },
  "name": "dataLif1",
  "probe_port": 64001,
  "rdma_protocols": [
    "roce"
  ],
  "scope": "string",
  "service_policy": {
    "_links": {
      "self": {
        "href": "/api/resourcelink"
      }
    },
    "name": "default-intercluster",
    "uuid": "1cd8a442-86d1-11e0-ae1c-123478563412"
  },
  "services": [
    "data_nfs"
  ],
  "state": "string",
  "statistics": {
    "status": "ok",
    "throughput_raw": {
      "read": 200,
      "total": 1000,
      "write": 100
    },
    "timestamp": "2017-01-25 06:20:13 -0500"
  },
  "subnet": {
    "_links": {
      "self": {
        "href": "/api/resourcelink"
      }
    },
    "name": "subnet1",
    "uuid": "1cd8a442-86d1-11e0-ae1c-123478563412"
  },
  "svm": {
    "_links": {
      "self": {
        "href": "/api/resourcelink"
      }
    },
    "name": "svm1",
    "uuid": "02c9e252-41be-11e9-81d5-00a0986138f7"
  },
  "uuid": "1cd8a442-86d1-11e0-ae1c-123478563412"
}

Response

Status: 201, Created
Name Type Description

_links

_links

num_records

integer

Number of records

recommend

recommend

Response properties specific to the LIF recommendation functionality.

records

array[ip_interface]
Example response 
{
  "_links": {
    "next": {
      "href": "/api/resourcelink"
    },
    "self": {
      "href": "/api/resourcelink"
    }
  },
  "num_records": 1,
  "recommend": {
    "messages": [
      {
      }
    ]
  },
  "records": [
    {
      "_links": {
        "self": {
          "href": "/api/resourcelink"
        }
      },
      "dns_zone": "storage.company.com",
      "ip": {
        "address": "10.10.10.7",
        "family": "string",
        "netmask": "24"
      },
      "ipspace": {
        "_links": {
          "self": {
            "href": "/api/resourcelink"
          }
        },
        "name": "Default",
        "uuid": "1cd8a442-86d1-11e0-ae1c-123478563412"
      },
      "location": {
        "broadcast_domain": {
          "_links": {
            "self": {
              "href": "/api/resourcelink"
            }
          },
          "name": "bd1",
          "uuid": "1cd8a442-86d1-11e0-ae1c-123478563412"
        },
        "failover": "string",
        "home_node": {
          "_links": {
            "self": {
              "href": "/api/resourcelink"
            }
          },
          "name": "node1",
          "uuid": "1cd8a442-86d1-11e0-ae1c-123478563412"
        },
        "home_port": {
          "_links": {
            "self": {
              "href": "/api/resourcelink"
            }
          },
          "name": "e1b",
          "node": {
            "name": "node1"
          },
          "uuid": "1cd8a442-86d1-11e0-ae1c-123478563412"
        },
        "node": {
          "_links": {
            "self": {
              "href": "/api/resourcelink"
            }
          },
          "name": "node1",
          "uuid": "1cd8a442-86d1-11e0-ae1c-123478563412"
        },
        "port": {
          "_links": {
            "self": {
              "href": "/api/resourcelink"
            }
          },
          "name": "e1b",
          "node": {
            "name": "node1"
          },
          "uuid": "1cd8a442-86d1-11e0-ae1c-123478563412"
        }
      },
      "metric": {
        "_links": {
          "self": {
            "href": "/api/resourcelink"
          }
        },
        "duration": "PT15S",
        "status": "ok",
        "throughput": {
          "read": 200,
          "total": 1000,
          "write": 100
        },
        "timestamp": "2017-01-25 06:20:13 -0500"
      },
      "name": "dataLif1",
      "probe_port": 64001,
      "rdma_protocols": [
        "roce"
      ],
      "scope": "string",
      "service_policy": {
        "_links": {
          "self": {
            "href": "/api/resourcelink"
          }
        },
        "name": "default-intercluster",
        "uuid": "1cd8a442-86d1-11e0-ae1c-123478563412"
      },
      "services": [
        "data_nfs"
      ],
      "state": "string",
      "statistics": {
        "status": "ok",
        "throughput_raw": {
          "read": 200,
          "total": 1000,
          "write": 100
        },
        "timestamp": "2017-01-25 06:20:13 -0500"
      },
      "subnet": {
        "_links": {
          "self": {
            "href": "/api/resourcelink"
          }
        },
        "name": "subnet1",
        "uuid": "1cd8a442-86d1-11e0-ae1c-123478563412"
      },
      "svm": {
        "_links": {
          "self": {
            "href": "/api/resourcelink"
          }
        },
        "name": "svm1",
        "uuid": "02c9e252-41be-11e9-81d5-00a0986138f7"
      },
      "uuid": "1cd8a442-86d1-11e0-ae1c-123478563412"
    }
  ]
}

Headers

Name Description Type

Location

Useful for tracking the resource location

string

Error

Status: Default

ONTAP Error Response Codes

Error Code Description

1376656

Cluster interfaces must be in the same subnet. Verify the address and netmask are set to the correct values.

1376663

All LIFs from a single DNS zone must be in the same SVM.

1376663

Cannot add interface to DNS zone because all interfaces from a single DNS zone must be in the same SVM.

1376963

Duplicate IP address.

1376976

The specified port is not capable of hosting this LIF.

1377583

Failed to create the interface because the broadcast domain of the specified subnet is different from the specified broadcast domain.

1377666

Subnet does not have any addresses available.

1966138

The same IP address may not be used for both a mgmt interface and a gateway address.

1966140

An interface with the same name already exists.

1966141

Invalid DNS zone name.

1966142

Only data LIFs can be assigned a DNS zone.

1966191

The interface could not be created because interface identifier creation failed.

1966217

Invalid port on the node.

1966267

IPv6 addresses must have a prefix length between 1 and 127.

1966269

IPv4 addresses must have a prefix length between 1 and 32.

1966270

Operation not support on SAN LIFs.

1966300

The LIF name is too long. The maximum number of characters allowed for iSCSI and FC LIF names is 254.

1966373

Failed to create interface because the home-port is not in the IPspace associated with the SVM.

1966454

A port on the node is not a member of a broadcast domain.

1966476

DNS Update is supported only on data LIFs.

1966477

DNS Update is supported only on LIFs configured with the NFS or CIFS protocol.

1966987

The Vserver Broadcast-Domain Home-Node and Home-Port combination is not valid.

1967081

The specified SVM must exist in the specified IPspace.

1967082

The specified ipspace.name does not match the IPspace name of ipspace.uuid.

1967102

POST operation might have left configuration in an inconsistent state. Check the configuration.

1967106

The specified location.home_port.name does not match the specified port name of location.home_port.uuid.

1967107

The location.home_port.uuid specified is not valid.

1967108

The specified location.home_node.name does not match the node name of location.home_node.uuid.

1967109

The specified location.home_port.node.name does not match the node name of location.home_node.uuid.

1967110

The specified location.home_port.node.name does not match location.home_node.name.

1967111

Home node must be specified by at least one location.home_node, location.home_port, or location.broadcast_domain field.

1967112

The specified location.home_node.name does not match the node name of location.home_port.uuid.

1967120

The specified service_policy.name does not match the specified service policy name of service_policy.uuid.

1967121

Invalid service_policy.uuid specified.

1967122

The specified location.broadcast_domain.name does not match the specified broadcast domain name of location.broadcast_domain.uuid.

1967123

The specified IPspace does not match the IPspace name of location.broadcast_domain.uuid.

1967124

The location.broadcast_domain.uuid specified is not valid.

1967127

svm.uuid or svm.name must be provided if scope is "svm".

1967128

ipspace.uuid or ipspace.name must be provided if scope is "cluster".

1967129

The specified location.home_port.uuid is not valid.

1967130

The specified location.home_port.name is not valid.

1967131

The specified location.home_port.uuid and location.home_port.name are not valid.

1967135

The specified location.broadcast_domain.uuid is not valid.

1967136

The specified location.broadcast_domain.name (and ipspace name) is not valid.

1967137

The specified location.broadcast_domain.uuid and location.broadcast_domain.name (and IPspace name) are not valid.

1967145

The specified location.failover is not valid.

1967146

The specified svm.name is not valid.

1967147

The specified svm.uuid is not valid.

1967153

No suitable port exists on location.home_node to host the interface.

1967154

Interfaces cannot be created on ports that are down. If a broadcast domain is specified, ensure that it contains at least one port that is operationally up.

1967381

Post VIP interfaces requires an effective cluster version of 9.7 or later.

1967382

VIP interfaces only reside in SVM scope.

1967383

Neither location.home_port.uuid or location.home_port.name should be set with vip=true.

1967384

Failed to create VIP interface because the home node does not have active BGP sessions to support Virtual IP (VIP) traffic.

1967385

VIP interfaces with an IPv4 address must use ip.netmask=32. VIP interfaces with an IPv6 address must use ip.netmask=128.

1967387

The specified IP address is in use by a subnet in this IPspace.

1967391

Setting the DNS zone requires an effective cluster version of 9.9.1 or later.

1967392

Setting the DDNS enable parameter requires an effective cluster version of 9.9.1 or later.

1967394

Setting the probe port parameter requires an effective cluster version of 9.10.1 or later.

1967396

The specified subnet.name does not match the subnet name of subnet.uuid.

1967397

The specified subnet.uuid does not match any configured subnet.";

1967398

Address must be specified by either ip.address and ip.netmask, or at least one subnet field, not both.";

1967401

The specified subnet.name does not match any configured subnet.

1967402

Data SVM cannot be specified with cluster scope.

2621519

Invalid SVM name. The SVM name must begin with a letter or an underscore. The maximum supported length is 41 if the SVM type is "sync-source", otherwise it is 47.

5373966

An iSCSI interface cannot be created in an SVM configured for NVMe.

8847378

Cannot specify DNS zone when DNS updates are enabled for SVM

53216540

LIFs on the specified SVM do not have a default service policy.

53281018

Failover policy is not compatible with one or more services in service policy

53281036

Setting the probe port parameter is not allowed on this platform.

53281065

The service_policy does not exist in the SVM.

53281073

IP address and netmask cannot be used because this represents a subnet address rather than a specific host address.

53281086

LIF would exceed the maximum number of supported intercluster LIFs in IPspace.

53281087

Cannot configure SAN LIF on SVM.

53281092

Failed to create interface because the home-port does not support the specified protocol.

53281104

The specified address is in use by the Service Processor

53281106

Failed checking the cluster capabilities.

53281114

The specified parameter is only supported on data SVMs.

53281680

Invalid value for the specified field.

Also see the table of common errors in the Response body overview section of this documentation.

Name Type Description

error

returned_error
Example error 
{
  "error": {
    "arguments": [
      {
        "code": "string",
        "message": "string"
      }
    ],
    "code": "4",
    "message": "entry doesn't exist",
    "target": "uuid"
  }
}

Definitions

See Definitions

href

Name Type Description

href

string

_links

Name Type Description

self

href

ip_info

IP information

Name Type Description

address

string

IPv4 or IPv6 address

family

string

IPv4 or IPv6

netmask

string

Input as netmask length (16) or IPv4 mask (255.255.0.0). For IPv6, the default value is 64 with a valid range of 1 to 127. Output is always the netmask length.

ipspace

Either the UUID or name must be supplied on POST for cluster-scoped objects.

Name Type Description

_links

_links

name

string

IPspace name

uuid

string

IPspace UUID

broadcast_domain

Broadcast domain UUID along with a readable name.

Name Type Description

_links

_links

name

string

Name of the broadcast domain, scoped to its IPspace

uuid

string

Broadcast domain UUID

home_node

Name Type Description

_links

_links

name

string

uuid

string

node

Name Type Description

name

string

Name of node on which the port is located.

home_port

Port UUID along with readable names. Either the UUID or both names may be supplied on input.

Name Type Description

_links

_links

name

string

node

node

uuid

string

node

Name Type Description

_links

_links

name

string

uuid

string

port

Port UUID along with readable names. Either the UUID or both names may be supplied on input.

Name Type Description

_links

_links

name

string

node

node

uuid

string

location

Current or home location can be modified. Specifying a port implies a node. Specifying a node allows an appropriate port to be automatically selected. Ports are not valid and not shown for VIP interfaces. For POST, broadcast_domain can be specified alone or with home_node. For PATCH, set is_home to true to revert a LIF back to its home port.

Name Type Description

auto_revert

boolean

broadcast_domain

broadcast_domain

Broadcast domain UUID along with a readable name.

failover

string

Policy that defines where an interface is permitted to move on failover. The policy named “default” implements the recommended best practice for NAS LIFs on the current platform and cluster, and was known as “system_defined” in the CLI.

home_node

home_node

home_port

home_port

Port UUID along with readable names. Either the UUID or both names may be supplied on input.

is_home

boolean

node

node

port

port

Port UUID along with readable names. Either the UUID or both names may be supplied on input.

throughput

The rate of throughput bytes per second observed at the interface.

Name Type Description

read

integer

Performance metric for read I/O operations.

total

integer

Performance metric aggregated over all types of I/O operations.

write

integer

Peformance metric for write I/O operations.

metric

The most recent sample of I/O metrics for the interface.

Name Type Description

_links

_links

duration

string

The duration over which this sample is calculated. The time durations are represented in the ISO-8601 standard format. Samples can be calculated over the following durations:

status

string

Errors associated with the sample. For example, if the aggregation of data over multiple nodes fails, then any partial errors might return "ok" on success or "error" on an internal uncategorized failure. Whenever a sample collection is missed but done at a later time, it is back filled to the previous 15 second timestamp and tagged with "backfilled_data". "inconsistent_delta_time" is encountered when the time between two collections is not the same for all nodes. Therefore, the aggregated value might be over or under inflated. "Negative_delta" is returned when an expected monotonically increasing value has decreased in value. "inconsistent_old_data" is returned when one or more nodes do not have the latest data.

throughput

throughput

The rate of throughput bytes per second observed at the interface.

timestamp

string

The timestamp of the performance data.

service_policy

Name Type Description

_links

_links

name

string

uuid

string

throughput_raw

Throughput bytes observed at the interface. This can be used along with delta time to calculate the rate of throughput bytes per unit of time.

Name Type Description

read

integer

Performance metric for read I/O operations.

total

integer

Performance metric aggregated over all types of I/O operations.

write

integer

Peformance metric for write I/O operations.

statistics

The real time I/O statistics for the interface.

Name Type Description

status

string

Errors associated with the sample. For example, if the aggregation of data over multiple nodes fails, then any partial errors might return "ok" on success or "error" on an internal uncategorized failure. Whenever a sample collection is missed but done at a later time, it is back filled to the previous 15 second timestamp and tagged with "backfilled_data". "inconsistent_delta_time" is encountered when the time between two collections is not the same for all nodes. Therefore, the aggregated value might be over or under inflated. "Negative_delta" is returned when an expected monotonically increasing value has decreased in value. "inconsistent_old_data" is returned when one or more nodes do not have the latest data.

throughput_raw

throughput_raw

Throughput bytes observed at the interface. This can be used along with delta time to calculate the rate of throughput bytes per unit of time.

timestamp

string

The timestamp of the performance data.

ip_subnet_reference

A named subnet. Either UUID or name can be supplied on input.

Name Type Description

_links

_links

name

string

The name of the subnet. If only the name is provided, the IPspace scope must be provided by the object this object is embedded in.

uuid

string

The UUID that uniquely identifies the subnet.

svm

Applies only to SVM-scoped objects. Either the UUID or name must be supplied on POST.

Name Type Description

_links

_links

name

string

The name of the SVM. This field cannot be specified in a PATCH method.

uuid

string

The unique identifier of the SVM. This field cannot be specified in a PATCH method.

ip_interface

Name Type Description

_links

_links

ddns_enabled

boolean

Indicates whether or not dynamic DNS updates are enabled. Defaults to true if the interface supports "data_nfs" or "data_cifs" services, otherwise false.

dns_zone

string

Fully qualified DNS zone name

enabled

boolean

The administrative state of the interface.

fail_if_subnet_conflicts

boolean

This command fails if the specified IP address falls within the address range of a named subnet. Set this value to false to use the specified IP address and to assign the subnet owning that address to the interface.

ip

ip_info

IP information

ipspace

ipspace

Either the UUID or name must be supplied on POST for cluster-scoped objects.

location

location

Current or home location can be modified. Specifying a port implies a node. Specifying a node allows an appropriate port to be automatically selected. Ports are not valid and not shown for VIP interfaces. For POST, broadcast_domain can be specified alone or with home_node. For PATCH, set is_home to true to revert a LIF back to its home port.

metric

metric

The most recent sample of I/O metrics for the interface.

name

string

Interface name

probe_port

integer

Probe port for Cloud load balancer

rdma_protocols

array[string]

Supported RDMA offload protocols

scope

string

Set to "svm" for interfaces owned by an SVM. Otherwise, set to "cluster".

service_policy

service_policy

services

array[string]

The services associated with the interface.

state

string

The operational state of the interface.

statistics

statistics

The real time I/O statistics for the interface.

subnet

ip_subnet_reference

A named subnet. Either UUID or name can be supplied on input.

svm

svm

Applies only to SVM-scoped objects. Either the UUID or name must be supplied on POST.

uuid

string

The UUID that uniquely identifies the interface.

vip

boolean

True for a VIP interface, whose location is announced via BGP.

_links

Name Type Description

next

href

self

href

ip_interface_recommend_message

recommend

Response properties specific to the LIF recommendation functionality.

Name Type Description

messages

array[ip_interface_recommend_message]

Messages describing the results of a LIF recommendation request.

error_arguments

Name Type Description

code

string

Argument code

message

string

Message argument

returned_error

Name Type Description

arguments

array[error_arguments]

Message arguments

code

string

Error code

message

string

Error message

target

string

The target parameter that caused the error.