Listing Network Ports
List network ports to which the project has access.
Default policy settings return only those ports that are owned by the project of the user who submits the request, unless the request is submitted by a user with administrative rights.
Request
GET /v2.0/ports
Parameters
| Name | In | Type | Description |
|---|---|---|---|
admin_state_up (Optional) | query | boolean | Filter the list result by the administrative state of the resource, which is up (true) or down (false). |
binding:host_id (Optional) | query | string | Filter the port list result by the ID of the host where the port resides. |
device_id (Optional) | query | string | Filter the port list result by the ID of the device that uses this port. For example, a server instance or a logical router. |
device_owner (Optional) | query | string | Filter the port result list by the entity type that uses this port. For example, compute:nova (server instance), network:dhcp (DHCP agent), or network:router_interface (router interface). |
id (Optional) | query | string | Filter the list result by the ID of the resource. |
fixed_ips (Optional) | query | array | Filter the port list result by the IP addresses for the port. This field has one or multiple entries. Each entry consists of an IP address (ip_address), an IP address substring (ip_address_substr), and/or the subnet ID from which the IP address is assigned (subnet_id). |
ip_allocation (Optional) | query | string | Filter the port list result based on whether the ports use deferred, immediate, or no IP allocation (none). |
mac_address (Optional) | query | string | Filter the port list result by the MAC address of the port. |
name (Optional) | query | string | Filter the list result by the human-readable name of the resource. |
network_id (Optional) | query | string | Filter the list result by the ID of the attached network. |
project_id (Optional) | query | string | Filter the list result by the ID of the project that owns the resource. |
revision_number (Optional) | query | integer | Filter the list result by the revision number of the port. |
status (Optional) | query | string | Filter the port list result by port status. Values are ACTIVE, DOWN, BUILD or ERROR. |
tenant_id (Optional) | query | string | Filter the list result by the ID of the project that owns the resource. |
description (Optional) | query | string | Filter the list result by the human-readable description of the port. |
mac_learning_enabled (Optional) | query | boolean | Filter the list result by the mac_learning_enabled state of the resource, which is enabled (true) or disabled (false). |
tags (Optional) | query | string | A list of tags to filter the list result by. Resources that match all tags in this list will be returned. Tags in query must be separated by comma. |
tags-any (Optional) | query | string | A list of tags to filter the list result by. Resources that match any tag in this list will be returned. Tags in query must be separated by comma. |
not-tags (Optional) | query | string | A list of tags to filter the list result by. Resources that match all tags in this list will be excluded. Tags in query must be separated by comma. |
not-tags-any (Optional) | query | string | A list of tags to filter the list result by. Resources that match any tag in this list will be excluded. Tags in query must be separated by comma. |
sort_dir (Optional) | query | string | Sort direction. A valid value is asc (ascending) or desc (descending). You can specify multiple pairs of sort key and sort direction query parameters. |
sort_key (Optional) | query | string | Sorts by a port attribute. You can specify multiple pairs of sort key and sort direction query parameters. The sort keys are limited to: admin_state_up, device_id, device_owner, id, ip_allocation, mac_address, name, network_id, project_id, status, tenant_id. |
fields (Optional) | query | string | The fields that you want the server to return. If no fields query parameter is specified, the networking API returns all attributes allowed by the policy settings. By using the fields parameter, the API returns only the requested set of attributes. The fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only the id and name attributes will be returned. |
Example Request
curl -ks -H 'Content-Type: application/json' -H 'X-Auth-Token: gAAAAA<...>' \
https://<node_IP_addr>:9696/v2.0/ports
Response
Response Parameters
| Name | In | Type | Description |
|---|---|---|---|
ports | body | array | A list of port objects. |
admin_state_up | body | boolean | The administrative state of the port, which is up (true) or down (false). |
allowed_address_pairs | body | array | A set of zero or more allowed address pair objects each where address pair object contains ip_address and mac_address. While ip_address is required, mac_address is taken from the port if not specified. The value of ip_address can be an IP address or a CIDR. A server connected to the port can send a packet with the source address that matches one of the specified allowed address pairs. |
binding:host_id | body | string | The ID of the host where the port resides. |
binding:profile | body | object | A dictionary that enables the application running on the specific host to pass and receive vif port information specific to the networking backend. The networking API does not define a specific format of this field. If the update request is null this response field will be {}. |
binding:vif_details | body | object | A dictionary that contains additional information on the port. Currently the following fields are defined: port_filter and ovs_hybrid_plug. port_filter is a boolean used to indicate if the networking service provides such port filtering features as security group and/or anti MAC/IP spoofing. ovs_hybrid_plug is a boolean used to inform an API consumer, like nova, that the hybrid plugging strategy for OVS should be used. |
binding:vif_type | body | string | The type of the mechanism that is used for the port. An API consumer like Nova can use this to determine an appropriate way to attach a device (for example, a VM interface) to the port. Available values currently defined include ovs, bridge, macvtap, hw_veb, hostdev_physical, vhostuser, distributed, and other. There are also special values: unbound and binding_failed. unbound means the port is not bound to a networking backend. binding_failed means that the port failed to be bound to a networking backend. |
binding:vnic_type | body | string | The type of the vNIC this port should be attached to. This is used to determine which mechanism driver(s) to be used to bind the port. The valid values are normal, macvtap, direct, baremetal, direct-physical, virtio-forwarder, smart-nic, and remote-managed. The type of the actually available vNIC depends on deployments. |
created_at | body | string | The date and time when the resource was created. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm. For example, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. |
data_plane_status | body | string | The status of the underlying data plane of the port. |
device_id | body | string | The ID of the device that uses this port. For example, a server instance or a logical router. |
device_owner | body | string | The entity type that uses this port. For example, compute:nova (server instance), network:dhcp (DHCP agent), or network:router_interface (router interface). |
dns_assignment | body | object | Data assigned to a port by the networking internal DNS including the hostname, ip_address, and fqdn. |
dns_domain | body | string | A valid DNS domain. |
id | body | string | The ID of the port. |
dns_name | body | string | A valid DNS name. |
extra_dhcp_opts | body | array | A set of zero or more extra DHCP option pairs. An option pair consists of an option value and name. |
fixed_ips | body | array | The IP addresses for the port. If the port has multiple IP addresses, this field has multiple entries. Each entry consists of an IP address (ip_address) and the subnet ID from which the IP address is assigned (subnet_id). |
hints | body | object | Admin-only. The following values control Open vSwitch's Userspace Tx packet steering feature: {"openvswitch": {"other_config": {"tx-steering": "hash|thread"}}} |
ip_allocation | body | string | Indicates whether the port uses deferred, immediate, or no IP allocation (none). |
mac_address | body | string | The MAC address of the port. If the port uses the direct-physical vnic_type, the value of this field is overwritten with the MAC address provided in the active binding:profile if any. |
name | body | string | Human-readable name of the port. |
network_id | body | string | The ID of the attached network. |
numa_affinity_policy (Optional) | body | string | The port NUMA affinity policy requested during the virtual machine scheduling. Values: none, required, preferred, or legacy. |
port_security_enabled | body | boolean | The port security status. Valid values are enabled (true) and disabled (false). If port security is enabled for the port, security group rules and anti-spoofing rules are applied to the traffic on the port. If disabled, no such rules are applied. |
project_id | body | string | The ID of the project. |
qos_network_policy_id | body | string | The ID of the QoS policy of the network where this port is plugged. |
qos_policy_id | body | string | The ID of the QoS policy associated with the port. |
revision_number | body | integer | The revision number of the port. |
resource_request (Optional) | body | object | Expose Placement resources (for example, minimum-bandwidth) and traits (for example, vnic-type, physnet) requested by a port to Nova and Placement. A resource_request object contains the request_groups and same_subtree keys. |
security_groups | body | array | The IDs of security groups applied to the port. |
status | body | string | The port status. Values are ACTIVE, DOWN, BUILD or ERROR. |
tenant_id | body | string | The ID of the project. |
updated_at | body | string | The date and time when the resource was updated. If the resource has not been updated, this field will be null. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm. For example, 2015-08-27T09:49:58-05:00. |
propagate_uplink_status | body | boolean | The uplink status propagation of the port. Valid values are enabled (true) and disabled (false). |
description | body | string | A human-readable description for the port. |
mac_learning_enabled (Optional) | body | boolean | A boolean value that indicates if MAC Learning is enabled on the associated port. |
port_trusted_vif | body | boolean | The port's trusted VIF status. A valid value is true or false. The value of this field is included in the binding:profile dict of the port. |
tags | body | array | The list of tags on the port. |
Status Codes
Success
| Code | Reason |
|---|---|
| 200 - OK | Request was successful. |
Error
| Code | Reason |
|---|---|
| 401 - Unauthorized | User must authenticate before making a request. |
Example Response
{
"ports": [
{
"id": "525584a7-2106-483a-b313-5f9fc23dee7f",
"name": "",
"network_id": "f858b8d1-e66b-4a48-bc2e-3f16483b1b58",
"tenant_id": "",
"mac_address": "fa:16:3e:b6:2e:7d",
"admin_state_up": true,
"status": "ACTIVE",
"device_id": "1c78faed-7262-403b-8f0a-097a77af8b65",
"device_owner": "network:router_centralized_snat",
"fixed_ips": [
{
"subnet_id": "adffaac8-2261-43f7-9e4f-6044230f65f1",
"ip_address": "192.168.1.61"
}
],
"allowed_address_pairs": [],
"extra_dhcp_opts": [],
"security_groups": [],
"description": "",
"binding:vnic_type": "normal",
"port_security_enabled": false,
"qos_policy_id": null,
"qos_network_policy_id": "dfc42ced-02c8-4b1f-bbe6-14cc014f259d",
"tags": [],
"created_at": "2025-09-30T09:20:01Z",
"updated_at": "2025-10-01T20:24:29Z",
"revision_number": 8,
"project_id": ""
},
{
"id": "726b31f7-4dde-4e93-a0cf-afeda1bfcaea",
"name": "",
"network_id": "f858b8d1-e66b-4a48-bc2e-3f16483b1b58",
"tenant_id": "f33507157a634f1cac71e06a70fb558e",
"mac_address": "fa:16:3e:17:7c:d0",
"admin_state_up": true,
"status": "ACTIVE",
"device_id": "dhcpe52a9a47-9f6a-5406-9193-a4d7333f9889-f858b8d1-e66b-4a48-bc2e-3f16483b1b58",
"device_owner": "network:dhcp",
"fixed_ips": [
{
"subnet_id": "adffaac8-2261-43f7-9e4f-6044230f65f1",
"ip_address": "192.168.1.2"
}
],
"allowed_address_pairs": [],
"extra_dhcp_opts": [],
"security_groups": [],
"description": "",
"binding:vnic_type": "normal",
"port_security_enabled": false,
"qos_policy_id": null,
"qos_network_policy_id": "dfc42ced-02c8-4b1f-bbe6-14cc014f259d",
"tags": [],
"created_at": "2025-09-30T09:19:36Z",
"updated_at": "2025-10-01T20:24:36Z",
"revision_number": 9,
"project_id": "f33507157a634f1cac71e06a70fb558e"
},
{
"id": "ef9338c5-8700-4ba4-8c10-d5ddd142a86e",
"name": "",
"network_id": "f858b8d1-e66b-4a48-bc2e-3f16483b1b58",
"tenant_id": "f33507157a634f1cac71e06a70fb558e",
"mac_address": "fa:16:3e:8e:1e:d1",
"admin_state_up": true,
"status": "ACTIVE",
"device_id": "dhcp5eed51fb-728a-5fc4-90a4-1a768a8a68da-f858b8d1-e66b-4a48-bc2e-3f16483b1b58",
"device_owner": "network:dhcp",
"fixed_ips": [
{
"subnet_id": "adffaac8-2261-43f7-9e4f-6044230f65f1",
"ip_address": "192.168.1.3"
}
],
"allowed_address_pairs": [],
"extra_dhcp_opts": [],
"security_groups": [],
"description": "",
"binding:vnic_type": "normal",
"port_security_enabled": false,
"qos_policy_id": null,
"qos_network_policy_id": "dfc42ced-02c8-4b1f-bbe6-14cc014f259d",
"tags": [],
"created_at": "2025-09-30T09:19:36Z",
"updated_at": "2025-10-01T20:26:15Z",
"revision_number": 15,
"project_id": "f33507157a634f1cac71e06a70fb558e"
},
{
"id": "f3247456-0e9a-4abb-bb37-2f0c002a9ada",
"name": "",
"network_id": "f858b8d1-e66b-4a48-bc2e-3f16483b1b58",
"tenant_id": "f33507157a634f1cac71e06a70fb558e",
"mac_address": "fa:16:3e:60:56:4c",
"admin_state_up": true,
"status": "ACTIVE",
"device_id": "1c78faed-7262-403b-8f0a-097a77af8b65",
"device_owner": "network:router_interface_distributed",
"fixed_ips": [
{
"subnet_id": "adffaac8-2261-43f7-9e4f-6044230f65f1",
"ip_address": "192.168.1.1"
}
],
"allowed_address_pairs": [],
"extra_dhcp_opts": [],
"security_groups": [],
"description": "",
"binding:vnic_type": "normal",
"port_security_enabled": false,
"qos_policy_id": null,
"qos_network_policy_id": "dfc42ced-02c8-4b1f-bbe6-14cc014f259d",
"tags": [],
"created_at": "2025-09-30T09:20:01Z",
"updated_at": "2025-09-30T09:20:12Z",
"revision_number": 14,
"project_id": "f33507157a634f1cac71e06a70fb558e"
}
]
}