Network Ethernet ports endpoint overview
Overview
A port is a physical or virtual Ethernet network device. Physical ports may be combined into Link Aggregation Groups (LAGs or ifgrps), or divided into Virtual LANs (VLANs).
GET (collection), GET (instance), and PATCH APIs are available for all port types. POST and DELETE APIs are available for "lag" (ifgrp) and "vlan" port types.
Retrieving network port information
The network ports GET API retrieves and displays relevant information pertaining to the ports configured in the cluster. The API retrieves the list of all ports configured in the cluster, or specifically requested ports. The fields returned in the response vary for different ports and configurations.
Examples
Retrieving all ports in the cluster
The following output displays the UUID, name, and port type for all ports configured in a 2-node cluster. The port types are physical, vlan, lag (ifgrp), and p-vlan (available in select environments only).
# The API: /api/network/ethernet/ports # The call: curl -X GET "https://<mgmt-ip>/api/network/ethernet/ports?fields=uuid,name,type" -H "accept: application/hal+json" # The response: { "records": [ { "uuid": "2d2c90c0-f70d-11e8-b145-005056bb5b8e", "name": "e0a", "type": "physical", "_links": { "self": { "href": "/api/network/ethernet/ports/2d2c90c0-f70d-11e8-b145-005056bb5b8e" } } }, { "uuid": "2d3004da-f70d-11e8-b145-005056bb5b8e", "name": "e0b", "type": "physical", "_links": { "self": { "href": "/api/network/ethernet/ports/2d3004da-f70d-11e8-b145-005056bb5b8e" } } }, { "uuid": "2d34a2cb-f70d-11e8-b145-005056bb5b8e", "name": "e0c", "type": "physical", "_links": { "self": { "href": "/api/network/ethernet/ports/2d34a2cb-f70d-11e8-b145-005056bb5b8e" } } }, { "uuid": "2d37189f-f70d-11e8-b145-005056bb5b8e", "name": "e0d", "type": "physical", "_links": { "self": { "href": "/api/network/ethernet/ports/2d37189f-f70d-11e8-b145-005056bb5b8e" } } }, { "uuid": "35de5d8b-f70d-11e8-abdf-005056bb7fc8", "name": "e0a", "type": "physical", "_links": { "self": { "href": "/api/network/ethernet/ports/35de5d8b-f70d-11e8-abdf-005056bb7fc8" } } }, { "uuid": "35de78cc-f70d-11e8-abdf-005056bb7fc8", "name": "e0b", "type": "physical", "_links": { "self": { "href": "/api/network/ethernet/ports/35de78cc-f70d-11e8-abdf-005056bb7fc8" } } }, { "uuid": "35dead3c-f70d-11e8-abdf-005056bb7fc8", "name": "e0c", "type": "physical", "_links": { "self": { "href": "/api/network/ethernet/ports/35dead3c-f70d-11e8-abdf-005056bb7fc8" } } }, { "uuid": "35deda90-f70d-11e8-abdf-005056bb7fc8", "name": "e0d", "type": "physical", "_links": { "self": { "href": "/api/network/ethernet/ports/35deda90-f70d-11e8-abdf-005056bb7fc8" } } }, { "uuid": "42e25145-f97d-11e8-ade9-005056bb7fc8", "name": "e0c-100", "type": "vlan", "_links": { "self": { "href": "/api/network/ethernet/ports/42e25145-f97d-11e8-ade9-005056bb7fc8" } } }, { "uuid": "569e0abd-f97d-11e8-ade9-005056bb7fc8", "name": "a0a", "type": "lag", "_links": { "self": { "href": "/api/network/ethernet/ports/569e0abd-f97d-11e8-ade9-005056bb7fc8" } } } ], "num_records": 10, "_links": { "self": { "href": "/api/network/ethernet/ports?fields=uuid,name,type" } } }
Retrieving a specific physical port
The following output displays the response when a specific physical port is requested. The system returns an error when there is no port with the requested UUID. Also, the "speed" field for the physical port is set only if the state of the port is up.
# The API: /api/network/ethernet/ports/{uuid} # The call: curl -X GET "https://<mgmt-ip>/api/network/ethernet/ports/2d37189f-f70d-11e8-b145-005056bb5b8e?fields=*" -H "accept: application/hal+json" # The response: { "uuid": "2d37189f-f70d-11e8-b145-005056bb5b8e", "name": "e0d", "mac_address": "00:50:56:bb:62:2d", "type": "physical", "node": { "uuid": "faa56898-f70c-11e8-b145-005056bb5b8e", "name": "user-cluster-01", "_links": { "self": { "href": "/api/cluster/nodes/faa56898-f70c-11e8-b145-005056bb5b8e" } } }, "broadcast_domain": { "uuid": "36434bec-f70d-11e8-b145-005056bb5b8e", "name": "Default", "ipspace": { "name": "Default" }, "_links": { "self": { "href": "/api/network/ethernet/broadcast-domains/36434bec-f70d-11e8-b145-005056bb5b8e" } } }, "enabled": true, "state": "up", "mtu": 1500, "speed": 1000, "reachability": "not_repairable", "reachable_broadcast_domains": [ { "uuid": "36434bec-f70d-11e8-b145-005056bb5b8e", "name": "Default", "ipspace": { "name": "Default" }, "_links": { "self": { "href": "/api/network/ethernet/broadcast-domains/36434bec-f70d-11e8-b145-005056bb5b8e" } } }, { "uuid": "df640ccf-72c4-11ea-b31d-005056bbfb29", "name": "Default-1", "ipspace": { "name": "Default" }, "_links": { "self": { "href": "/api/network/ethernet/broadcast-domains/df640ccf-72c4-11ea-b31d-005056bbfb29" } } } ], "_links": { "self": { "href": "/api/network/ethernet/ports/2d37189f-f70d-11e8-b145-005056bb5b8e" } } }
Retrieving a specific VLAN port
The following output displays the response when a specific VLAN port is requested. The system returns an error when there is no port with the requested UUID. Also, the "speed" field for a VLAN port is always set to zero if the state of the port is up. If the state of the port is down, the "speed" field is unset and not reported back.
# The API: /api/network/ethernet/ports/{uuid} # The call: curl -X GET "https://<mgmt-ip>/api/network/ethernet/ports/42e25145-f97d-11e8-ade9-005056bb7fc8?fields=*" -H "accept: application/hal+json" # The response: { "uuid": "42e25145-f97d-11e8-ade9-005056bb7fc8", "name": "e0e-100", "mac_address": "00:50:56:bb:52:2f", "type": "vlan", "node": { "uuid": "6042cf47-f70c-11e8-abdf-005056bb7fc8", "name": "user-cluster-02", "_links": { "self": { "href": "/api/cluster/nodes/6042cf47-f70c-11e8-abdf-005056bb7fc8" } } }, "broadcast_domain": { "uuid": "36434bec-f70d-11e8-b145-005056bb5b8e", "name": "Default", "ipspace": { "name": "Default" }, "_links": { "self": { "href": "/api/network/ethernet/broadcast-domains/36434bec-f70d-11e8-b145-005056bb5b8e" } } }, "enabled": true, "state": "up", "mtu": 1500, "speed": 0, "reachability": "ok", "reachable_broadcast_domains": [ { "uuid": "36434bec-f70d-11e8-b145-005056bb5b8e", "name": "Default", "ipspace": { "name": "Default" }, "_links": { "self": { "href": "/api/network/ethernet/broadcast-domains/36434bec-f70d-11e8-b145-005056bb5b8e" } } } ], "vlan": { "tag": 100, "base_port": { "uuid": "35deff03-f70d-11e8-abdf-005056bb7fc8", "name": "e0e", "node": { "name": "user-cluster-02" }, "_links": { "self": { "href": "/api/network/ethernet/ports/35deff03-f70d-11e8-abdf-005056bb7fc8" } } } }, "_links": { "self": { "href": "/api/network/ethernet/ports/42e25145-f97d-11e8-ade9-005056bb7fc8" } } }
Retrieving a specific LAG port
The following output displays the response when a specific LAG port is requested. The system returns an error when there is no port with the requested UUID. The "lag.active_ports" field is set only if the state of the port is up. Also, the "speed" field for a LAG port is always set to zero if the state of the port is up. If the state of the port is down, the "speed" field is unset and not reported back.
# The API: /api/network/ethernet/ports/{uuid} # The call: curl -X GET "https://<mgmt-ip>/api/network/ethernet/ports/569e0abd-f97d-11e8-ade9-005056bb7fc8?fields=*" -H "accept: application/hal+json" # The response: { "uuid": "569e0abd-f97d-11e8-ade9-005056bb7fc8", "name": "a0a", "mac_address": "02:50:56:bb:7f:c8", "type": "lag", "node": { "uuid": "6042cf47-f70c-11e8-abdf-005056bb7fc8", "name": "user-cluster-02", "_links": { "self": { "href": "/api/cluster/nodes/6042cf47-f70c-11e8-abdf-005056bb7fc8" } } }, "broadcast_domain": { "uuid": "36434bec-f70d-11e8-b145-005056bb5b8e", "name": "Default", "ipspace": { "name": "Default" }, "_links": { "self": { "href": "/api/network/ethernet/broadcast-domains/36434bec-f70d-11e8-b145-005056bb5b8e" } } }, "enabled": true, "state": "up", "mtu": 1500, "speed": 0, "reachability": "repairable", "reachable_broadcast_domains": [ { "uuid": "c7934b4f-691f-11ea-87fd-005056bb1ad3", "name": "Default", "ipspace": { "name": "Default" }, "_links": { "self": { "href": "/api/network/ethernet/broadcast-domains/c7934b4f-691f-11ea-87fd-005056bb1ad3" } } } ], "lag": { "mode": "singlemode", "distribution_policy": "mac", "member_ports": [ { "uuid": "35df318d-f70d-11e8-abdf-005056bb7fc8", "name": "e0f", "node": { "name": "user-cluster-02" }, "_links": { "self": { "href": "/api/network/ethernet/ports/35df318d-f70d-11e8-abdf-005056bb7fc8" } } }, { "uuid": "35df5bad-f70d-11e8-abdf-005056bb7fc8", "name": "e0g", "node": { "name": "user-cluster-02" }, "_links": { "self": { "href": "/api/network/ethernet/ports/35df5bad-f70d-11e8-abdf-005056bb7fc8" } } }, { "uuid": "35df9926-f70d-11e8-abdf-005056bb7fc8", "name": "e0h", "node": { "name": "user-cluster-02" }, "_links": { "self": { "href": "/api/network/ethernet/ports/35df9926-f70d-11e8-abdf-005056bb7fc8" } } } ], "active_ports": [ { "uuid": "35df318d-f70d-11e8-abdf-005056bb7fc8", "name": "e0f", "_links": { "self": { "href": "/api/network/ethernet/ports/35df318d-f70d-11e8-abdf-005056bb7fc8" } } } ] }, "_links": { "self": { "href": "/api/network/ethernet/ports/569e0abd-f97d-11e8-ade9-005056bb7fc8" } } }
Retrieving all LAG (ifgrp) ports in the cluster
This command retrieves all LAG ports in the cluster (that is, all ports with type=LAG). The example shows how to filter a GET collection based on type.
# The API: /api/network/ethernet/ports # The call: curl -X GET "https://<mgmt-ip>/api/network/ethernet/ports?type=lag&node.name=user-cluster-01&fields=name,enabled,speed,mtu" -H "accept: application/hal+json" # The response: { "records": [ { "uuid": "0c226db0-4b63-11e9-8113-005056bbe040", "name": "a0b", "type": "lag", "node": { "name": "user-cluster-01" }, "enabled": true, "mtu": 1500, "speed": 0, "_links": { "self": { "href": "/api/network/ethernet/ports/0c226db0-4b63-11e9-8113-005056bbe040" } } }, { "uuid": "d3a84153-4b3f-11e9-a00d-005056bbe040", "name": "a0a", "type": "lag", "node": { "name": "user-cluster-01" }, "enabled": true, "mtu": 1500, "speed": 0, "_links": { "self": { "href": "/api/network/ethernet/ports/d3a84153-4b3f-11e9-a00d-005056bbe040" } } } ], "num_records": 2, "_links": { "self": { "href": "/api/network/ethernet/ports?fields=name,enabled,speed,mtu&type=lag&node.name=user-cluster-01" } } }
Creating VLAN and LAG ports
You can use the network ports POST API to create VLAN and LAG ports. If you supply the optional broadcast domain property, the specified broadcast domain will be assigned to the new port immediately. Otherwise, within a few minutes automatic probing will determine the correct broadcast domain and will assign it to the port. During that period of time, the port will not be capable of hosting interfaces.
Examples
Creating a VLAN port
The following output displays the record returned after the creation of a VLAN port on "e0e" and VLAN tag "100".
# The API: /api/network/ethernet/ports # The call: curl -X POST "https://<mgmt-ip>/api/network/ethernet/ports?return_records=true" -H "accept: application/hal+json" -H "Content-Type: application/json" -d "{ \"type\": \"vlan\", \"node\": { \"name\": \"user-cluster-01\" }, \"enabled\": true, \"vlan\": { \"tag\": 100, \"base_port\": { \"name\": \"e0e\", \"node\": { \"name\": \"user-cluster-01\" } } }}" # The response: { "num_records": 1, "records": [ { "uuid": "88b2f682-fa42-11e8-a6d7-005056bb5b8e", "type": "vlan", "node": { "uuid": "faa56898-f70c-11e8-b145-005056bb5b8e", "name": "user-cluster-01", "_links": { "self": { "href": "/api/cluster/nodes/faa56898-f70c-11e8-b145-005056bb5b8e" } } }, "enabled": true, "vlan": { "tag": 100, "base_port": { "uuid": "2d39df72-f70d-11e8-b145-005056bb5b8e", "name": "e0e", "node": { "name": "user-cluster-01" }, "_links": { "self": { "href": "/api/network/ethernet/ports/2d39df72-f70d-11e8-b145-005056bb5b8e" } } } }, "_links": { "self": { "href": "/api/network/ethernet/ports/88b2f682-fa42-11e8-a6d7-005056bb5b8e" } } } ] }
Creating a VLAN port in a specific broadcast domain
The following output displays the record returned after the creation of a VLAN port on "e0e" and VLAN tag "100". Also, the VLAN port is added to the "Default" broadcast domain in the "Default" IPspace.
# The API: /api/network/ethernet/ports # The call: curl -X POST "https://<mgmt-ip>/api/network/ethernet/ports?return_records=true" -H "accept: application/hal+json" -H "Content-Type: application/json" -d "{ \"type\": \"vlan\", \"node\": { \"name\": \"user-cluster-01\" }, \"broadcast_domain\": { \"name\": \"Default\", \"ipspace\": { \"name\": \"Default \" } }, \"enabled\": true, \"vlan\": { \"tag\": 100, \"base_port\": { \"name\": \"e0e\", \"node\": { \"name\": \"user-cluster-01\" } } }}" # The response: { "num_records": 1, "records": [ { "uuid": "88b2f682-fa42-11e8-a6d7-005056bb5b8e", "type": "vlan", "node": { "uuid": "faa56898-f70c-11e8-b145-005056bb5b8e", "name": "user-cluster-01", "_links": { "self": { "href": "/api/cluster/nodes/faa56898-f70c-11e8-b145-005056bb5b8e" } } }, "broadcast_domain": { "uuid": "36434bec-f70d-11e8-b145-005056bb5b8e", "name": "Default", "ipspace": { "name": "Default" }, "_links": { "self": { "href": "/api/network/ethernet/broadcast-domains/36434bec-f70d-11e8-b145-005056bb5b8e" } } }, "enabled": true, "vlan": { "tag": 100, "base_port": { "uuid": "2d39df72-f70d-11e8-b145-005056bb5b8e", "name": "e0e", "node": { "name": "user-cluster-01" }, "_links": { "self": { "href": "/api/network/ethernet/ports/2d39df72-f70d-11e8-b145-005056bb5b8e" } } } }, "_links": { "self": { "href": "/api/network/ethernet/ports/88b2f682-fa42-11e8-a6d7-005056bb5b8e" } } } ] }
Creating a LAG (ifgrp) port
The following output displays the record returned after the creation of a LAG port with "e0f", "e0g" and "e0h" as member ports.
# The API: /api/network/ethernet/ports # The call: curl -X POST "https://<mgmt-ip>/api/network/ethernet/ports?return_records=true" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"type\": \"lag\", \"node\": { \"name\": \"user-cluster-01\" }, \"enabled\": true, \"lag\": { \"mode\": \"singlemode\", \"distribution_policy\": \"mac\", \"member_ports\": [ { \"name\": \"e0f\", \"node\": { \"name\": \"user-cluster-01\" } }, { \"name\": \"e0g\", \"node\": { \"name\": \"user-cluster-01\" }}, { \"name\": \"e0h\", \"node\": { \"name\": \"user-cluster-01\" } } ] } }" # The response: { "num_records": 1, "records": [ { "uuid": "1807772a-fa4d-11e8-a6d7-005056bb5b8e", "type": "lag", "node": { "uuid": "faa56898-f70c-11e8-b145-005056bb5b8e", "name": "user-cluster-01" }, "enabled": true, "lag": { "mode": "singlemode", "distribution_policy": "mac", "member_ports": [ { "uuid": "2d3c9adc-f70d-11e8-b145-005056bb5b8e", "name": "e0f", "node": { "name": "user-cluster-01" } }, { "uuid": "2d40b097-f70d-11e8-b145-005056bb5b8e", "name": "e0g", "node": { "name": "user-cluster-01" } }, { "uuid": "2d46d01e-f70d-11e8-b145-005056bb5b8e", "name": "e0h", "node": { "name": "user-cluster-01" } } ] } } ] }
Creating a LAG (ifgrp) port in a specific broadcast domain
The following output displays the record returned after the creation of a LAG port with "e0f", "e0g" and "e0h" as member ports. Also, the LAG port is added to the "Default" broadcast domain in the "Default" IPspace.
# The API: /api/network/ethernet/ports # The call: curl -X POST "https://<mgmt-ip>/api/network/ethernet/ports?return_records=true" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"type\": \"lag\", \"node\": { \"name\": \"user-cluster-01\" }, \"broadcast_domain\": { \"name\": \"Default\", \"ipspace\": { \"name\": \"Default\" } }, \"enabled\": true, \"lag\": { \"mode\": \"singlemode\", \"distribution_policy\": \"mac\", \"member_ports\": [ { \"name\": \"e0f\", \"node\": { \"name\": \"user-cluster-01\" } }, { \"name\": \"e0g\", \"node\": { \"name\": \"user-cluster-01\" }}, { \"name\": \"e0h\", \"node\": { \"name\": \"user-cluster-01\" } } ] } }" # The response: { "num_records": 1, "records": [ { "uuid": "1807772a-fa4d-11e8-a6d7-005056bb5b8e", "type": "lag", "node": { "uuid": "faa56898-f70c-11e8-b145-005056bb5b8e", "name": "user-cluster-01" }, "broadcast_domain": { "uuid": "36434bec-f70d-11e8-b145-005056bb5b8e", "name": "Default", "ipspace": { "name": "Default" } }, "enabled": true, "lag": { "mode": "singlemode", "distribution_policy": "mac", "member_ports": [ { "uuid": "2d3c9adc-f70d-11e8-b145-005056bb5b8e", "name": "e0f", "node": { "name": "user-cluster-01" } }, { "uuid": "2d40b097-f70d-11e8-b145-005056bb5b8e", "name": "e0g", "node": { "name": "user-cluster-01" }