Listing Network Ports

GET/v2.0/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

Parameters

admin_state_upboolean

Filter the list result by the administrative state of the resource, which is up (true) or down (false).

binding:host_idstring

Filter the port list result by the ID of the host where the port resides.

device_idstring

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_ownerstring

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).

idstring

Filter the list result by the ID of the resource.

fixed_ipsarray

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_allocationstring

Filter the port list result based on whether the ports use deferred, immediate, or no IP allocation (none).

mac_addressstring

Filter the port list result by the MAC address of the port.

namestring

Filter the list result by the human-readable name of the resource.

network_idstring

Filter the list result by the ID of the attached network.

project_idstring

Filter the list result by the ID of the project that owns the resource.

revision_numberinteger

Filter the list result by the revision number of the port.

statusstring

Filter the port list result by port status. Values are ACTIVE, DOWN, BUILD or ERROR.

tenant_idstring

Filter the list result by the ID of the project that owns the resource.

descriptionstring

Filter the list result by the human-readable description of the port.

mac_learning_enabledboolean

Filter the list result by the mac_learning_enabled state of the resource, which is enabled (true) or disabled (false).

tagsstring

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-anystring

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-tagsstring

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-anystring

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_dirstring

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_keystring

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.

fieldsstring

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

portsarrayrequired

A list of port objects.

admin_state_upbooleanrequired

The administrative state of the port, which is up (true) or down (false).

allowed_address_pairsarrayrequired

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_idstringrequired

The ID of the host where the port resides.

binding:profileobjectrequired

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_detailsobjectrequired

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_typestringrequired

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_typestringrequired

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_atstringrequired

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_statusstringrequired

The status of the underlying data plane of the port.

device_idstringrequired

The ID of the device that uses this port. For example, a server instance or a logical router.

device_ownerstringrequired

The entity type that uses this port. For example, compute:nova (server instance), network:dhcp (DHCP agent), or network:router_interface (router interface).

dns_assignmentobjectrequired

Data assigned to a port by the networking internal DNS including the hostname, ip_address, and fqdn.

dns_domainstringrequired

A valid DNS domain.

idstringrequired

The ID of the port.

dns_namestringrequired

A valid DNS name.

extra_dhcp_optsarrayrequired

A set of zero or more extra DHCP option pairs. An option pair consists of an option value and name.

fixed_ipsarrayrequired

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).

hintsobjectrequired

Admin-only. The following values control Open vSwitch's Userspace Tx packet steering feature: {"openvswitch": {"other_config": {"tx-steering": "hash|thread"}}}

ip_allocationstringrequired

Indicates whether the port uses deferred, immediate, or no IP allocation (none).

mac_addressstringrequired

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 if any.

namestringrequired

Human-readable name of the port.

network_idstringrequired

The ID of the attached network.

numa_affinity_policystring

The port NUMA affinity policy requested during the virtual machine scheduling. Values: none, required, preferred, or legacy.

port_security_enabledbooleanrequired

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_idstringrequired

The ID of the project.

qos_network_policy_idstringrequired

The ID of the QoS policy of the network where this port is plugged.

qos_policy_idstringrequired

The ID of the QoS policy associated with the port.

revision_numberintegerrequired

The revision number of the port.

resource_requestobject

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_groupsarrayrequired

The IDs of security groups applied to the port.

statusstringrequired

The port status. Values are ACTIVE, DOWN, BUILD or ERROR.

tenant_idstringrequired

The ID of the project.

updated_atstringrequired

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_statusbooleanrequired

The uplink status propagation of the port. Valid values are enabled (true) and disabled (false).

descriptionstringrequired

A human-readable description for the port.

mac_learning_enabledboolean

A boolean value that indicates if MAC Learning is enabled on the associated port.

port_trusted_vifbooleanrequired

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.

tagsarrayrequired

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

Response body

{
    "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"
        }
    ]
}