Showing network port details

GET /v2.0/ports/{port_id}

Shows the details of a port with the specified ID.

Source: https://docs.openstack.org/api-ref/network/v2/index.html#show-port-details

Request

Parameters

Name	In	Type	Description
`port_id`	path	string	The ID of the port.
`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

# curl -ks -H 'Content-Type: application/json' -H 'X-Auth-Token: gAAAAA<...>' \
https://<node_IP_addr>:9696/v2.0/ports/c85ae844-9ff5-4866-97da-546c3bf0144b

Response

Parameters

Name	In	Type	Description
`port`	body	object	A `port` object.
`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. In this example, the offset value is `-05:00`.
`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. `request_groups` is a list of dicts, where each dict represents one group of resources and traits that needs to be fulfilled from a single resource provider. Every dict in the list must contain the `id`, `required`, and `resources` keys. The `id` field is a string which represents a unique UUID that is generated for each group by combining `port_id` and UUIDs of the QoS rules contributing to the group via the UUID5 method. The `required` key contains the traits (generated from `vnic_type` and `physnet`) required by the port, and the `resources` key contains a mapping of the requested resource class name and requested amount from the QoS policy. The `same_subtree` key contains a list of `id` values from every resource group.
`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`. 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`).
`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.
`404 - Not Found`	The requested resource could not be found.

Example

{
  "port": {
    "id": "c85ae844-9ff5-4866-97da-546c3bf0144b",
    "name": "private-port",
    "network_id": "cfbb5d6e-aa97-4efd-8a74-30597027fc8d",
    "tenant_id": "8bf97a9e3b8c41ac9a6722503544941d",
    "mac_address": "fa:16:3e:3a:74:d9",
    "admin_state_up": true,
    "status": "DOWN",
    "device_id": "",
    "device_owner": "",
    "fixed_ips": [
      {
        "subnet_id": "66031a48-8534-4b64-a578-533d865fe174",
        "ip_address": "192.168.128.232"
      }
    ],
    "project_id": "8bf97a9e3b8c41ac9a6722503544941d",
    "port_security_enabled": true,
    "qos_policy_id": null,
    "security_groups": [
      "2852b920-8106-4e9f-9298-c96356a9cc0a"
    ],
    "binding:vnic_type": "normal",
    "binding:profile": {},
    "binding:host_id": "",
    "binding:vif_type": "unbound",
    "binding:vif_details": {},
    "allowed_address_pairs": [
      {
        "mac_address": "fa:14:2a:b3:cb:f0",
        "ip_address": "192.168.128.100"
      }
    ],
    "extra_dhcp_opts": [],
    "description": "",
    "qos_network_policy_id": null,
    "resource_request": null,
    "tags": [],
    "created_at": "2024-11-18T19:37:20Z",
    "updated_at": "2024-11-18T19:37:21Z",
    "revision_number": 1
  }
}