Listing virtual router interfaces

GET /v2.0/ports

Lists ports to which the user has access.

You can use this call to find out port IDs of a virtual router with the specified ID.

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.

If the ip-substring-filtering extension is enabled, the Neutron API supports IP address substring filtering on the fixed_ips attribute. If you specify an IP address substring (ip_address_substr) in an entry of the fixed_ips attribute, the Neutron API will list all ports that have an IP address matching the substring.

Source: https://docs.openstack.org/api-ref/network/v2/index.html?expanded=list-ports-detail#list-ports

Request

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.
description (Optional) query string Filter the list result by the human-readable description of the port.
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).
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 IP address (ip_address), IP address substring (ip_address_substr) and/or the subnet ID from which the IP address is assigned (subnet_id).
id (Optional) query string Filter the list result by the ID of the resource.
ip_allocation (Optional) query string Filter the port list result based on if 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 resource.
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
status (Optional) query string Filter the port list result by the port status. Values are ACTIVE, DOWN, BUILD and ERROR.
tenant_id (Optional) query string Filter the list result by the ID of the project that owns the resource.
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.
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.
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).

Example

# curl -ks -H 'Content-Type: application/json' -H 'X-Auth-Token: gAAAAA<...>' \
https://<node_IP_addr>:9696/v2.0/ports?device_id=ce996632-45a2-4c6b-a951-a624eba74621

Response

Parameters

Name In Type Description
ports body array A list of port objects.
admin_state_up body boolean The administrative state of the resource, 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 an ip_address and mac_address. While the ip_address is required, the mac_address will be taken from the port if not specified. The value of ip_address can be an IP Address or a CIDR (if supported by the underlying extension plugin). A server connected to the port can send a packet with source address which 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 back-end. The networking API does not define a specific format of this field.
binding:vif_details body object A dictionary which contains additional information on the port. Currently the following fields are defined: port_filter and ovs_hybrid_plug. port_filter is a boolean indicating the networking service provides port filtering features such 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 which mechanism is used for the port. An API consumer like nova can use this to determine an appropriate way to attach a device (for example an interface of a virtual server) to the port. Available values currently defined includes 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 back-end. binding_failed means an error that the port failed to be bound to a networking back-end.
binding:vnic_type body string The type of vNIC which 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 and smart-nic. What type of vNIC is actually available 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. In this example, the offset value is -05:00.

data_plane_status body string Status of the underlying data plane of a port.
description body string A human-readable description for 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.
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 IP address (ip_address) and the subnet ID from which the IP address is assigned (subnet_id).
id body string The ID of the resource.
ip_allocation body string Indicates when ports use either deferred, immediate or no IP allocation (none).
mac_address body string The MAC address of the port.
name body string Human-readable name of the resource.
network_id body string The ID of the attached network.
port_security_enabled body boolean The port security status. A valid value is enabled (true) or 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 resource.
resource_request (Optional) body object Expose Placement resources (i.e.: minimum-bandwidth) and traits (i.e.: vnic-type, physnet) requested by a port to Nova and Placement. A resource_request object contains a required key for the traits (generated from the vnic_type and the physnet) required by the port, and a resources key for ingress and egress minimum-bandwidth need for the port.
security_groups body array The IDs of security groups applied to the port.
status body string The port status. Values are ACTIVE, DOWN, BUILD and ERROR.
tenant_id body string The ID of the project.
tags body array The list of tags on the resource.
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.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In this example, the offset value is -05:00.

propagate_uplink_status body boolean The uplink status propagation of the port. Valid values are enabled (true) and disabled (false).
mac_learning_enabled (Optional) body boolean A boolean value that indicates if MAC Learning is enabled on the associated port.

Status codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
401 - Unauthorized

User must authenticate before making a request.

Example

{
  "ports": [
    {
      "allowed_address_pairs": [],
      "extra_dhcp_opts": [],
      "updated_at": "2020-03-04T15:22:48Z",
      "device_owner": "network:router_gateway",
      "revision_number": 4,
      "port_security_enabled": false,
      "binding:profile": {},
      "fixed_ips": [
        {
          "subnet_id": "351884c7-ee37-4a7d-9dcb-4cff4a1bba27",
          "ip_address": "10.94.139.172"
        }
      ],
      "id": "0e9413cf-34f5-456f-851e-b2f1027b71bd",
      "security_groups": [],
      "binding:vif_details": {
        "port_filter": true,
        "bridge_name": "br-int",
        "datapath_type": "system",
        "ovs_hybrid_plug": false
      },
      "binding:vif_type": "ovs",
      "mac_address": "fa:16:3e:b6:fd:c4",
      "project_id": "",
      "status": "ACTIVE",
      "binding:host_id": "node1.vstoragedomain",
      "description": "",
      "tags": [],
      "device_id": "ce996632-45a2-4c6b-a951-a624eba74621",
      "name": "",
      "admin_state_up": true,
      "network_id": "b4907761-8c0f-447e-9cfe-c688ca6e44a0",
      "tenant_id": "",
      "created_at": "2020-03-04T15:22:41Z",
      "binding:vnic_type": "normal"
    },
    {
      "allowed_address_pairs": [],
      "extra_dhcp_opts": [],
      "updated_at": "2020-03-04T15:22:56Z",
      "device_owner": "network:router_interface",
      "revision_number": 5,
      "port_security_enabled": false,
      "binding:profile": {},
      "fixed_ips": [
        {
          "subnet_id": "112f9b9c-7be2-41c9-8c31-903b263353e7",
          "ip_address": "192.168.0.1"
        }
      ],
      "id": "5374d25d-edfe-40dd-ae1e-bef883d8e72d",
      "security_groups": [],
      "binding:vif_details": {
        "port_filter": true,
        "bridge_name": "br-int",
        "datapath_type": "system",
        "ovs_hybrid_plug": false
      },
      "binding:vif_type": "ovs",
      "mac_address": "fa:16:3e:13:20:14",
      "project_id": "f5d834d636c642c7bfe8af86139c6f26",
      "status": "ACTIVE",
      "binding:host_id": "node1.vstoragedomain",
      "description": "",
      "tags": [],
      "device_id": "ce996632-45a2-4c6b-a951-a624eba74621",
      "name": "",
      "admin_state_up": true,
      "network_id": "c4e2f31b-fe3b-402b-ac1b-b182693f72f7",
      "tenant_id": "f5d834d636c642c7bfe8af86139c6f26",
      "created_at": "2020-03-04T15:22:44Z",
      "binding:vnic_type": "normal"
    }
  ]
}