Prev Next

10.5. 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#list-ports

10.5.1. Request¶

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 resource.
`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 `fields` parameter, the API returns only the requested set of attributes. `fields` parameter can be specified multiple times. For example, if you specify `fields=id&fields=name` in the request URL, only `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`).

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

10.5.2. Response¶

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	Time at which the resource has been created (in UTC ISO8601 format).
`data_plane_status`	body	string	Status of the underlying data plane of a port.
`description`	body	string	A human-readable description for the resource.
`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`.
`tags`	body	array	The list of tags on the resource.
`tenant_id`	body	string	The ID of the project.
`updated_at`	body	string	Time at which the resource has been updated (in UTC ISO8601 format).
`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.

10.5.2.1. Status codes¶

10.5.2.1.1. Success¶

Code	Reason
`200 - OK`	Request was successful.

10.5.2.1.2. Error¶

Code	Reason
`401 - Unauthorized`	User must authenticate before making a request.

10.5.2.2. 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"
    }
  ]
}

Version 5.0.0 — Feb 01, 2022

Prev Next