Update Network Port

PUT/v2.0/ports/{port_id}

Update attributes of an existing network port.

Only mutable fields can be changed. Fields such as id, network_id, project_id / tenant_id, and timestamps are read-only.

Request

Path Parameters

port_idstringrequired

ID of the port to update.

Body Structure

Top-level JSON object must contain a single port object with one or more updatable attributes.

Updatable Parameters

portobjectrequired

Wrapper object containing the fields to update. Provide only the fields you want to change.

namestring

Human‑readable name of the port.

descriptionstring

Human‑readable description (empty string by default).

admin_state_upboolean

Administrative state: up (true) or down (false).

device_idstring

ID of the device (server, router, etc.) using this port.

device_ownerstring

Entity type using the port (compute:nova, network:dhcp, network:router_interface, etc.).

security_groupsarray

List of security group IDs to apply. Replaces the existing list.

fixed_ipsarray

New list of fixed IP mappings. Each entry may include subnet_id and/or ip_address. Entire list is replaced if provided. See create docs for allocation logic.

allowed_address_pairsarray

List of objects each with ip_address (required) and optional mac_address. Replaces existing list.

extra_dhcp_optsarray

List of DHCP option objects (opt_name, opt_value). Replaces existing list.

port_security_enabledboolean

Enable/disable security group & anti‑spoofing enforcement.

qos_policy_idstring

QoS policy to associate (or null to clear).

binding:host_idstring

Host ID where the port resides. Typically set by the system / scheduler; admin override only.

binding:profileobject

Backend‑specific VIF info dict. Use null to reset to {}. May contain device_mac_address for direct-physical binding to override the exposed mac_address.

binding:vnic_typestring

Desired vNIC type (normal, macvtap, direct, baremetal, direct-physical, virtio-forwarder, smart-nic, remote-managed). Changing after initial binding may be restricted by deployment.

mac_addressstring

Port MAC address. Usually immutable after creation except in specific binding scenarios (e.g. with direct-physical and device_mac_address).

dns_domainstring

DNS domain to associate.

dns_namestring

DNS name (hostname) to associate.

hintsobject

Admin-only mechanism driver hints (e.g. {"openvswitch": {"other_config": {"tx-steering": "hash"}}}). Max length 4095 chars serialized.

numa_affinity_policystring

NUMA affinity policy: none, required, preferred, or legacy.

propagate_uplink_statusboolean

Whether uplink status propagation is enabled.

mac_learning_enabledboolean

Enable MAC learning on the port.

port_trusted_vifboolean

Trusted VIF status. Reflected within binding:profile.

allowed_address_pairs[*].ip_addressstringrequired

IP address or CIDR.

allowed_address_pairs[*].mac_addressstring

MAC address; defaults to port MAC if omitted.

Note: Omitted fields are left unchanged. For list‑type attributes (e.g. security_groups, allowed_address_pairs, fixed_ips), supplying a list replaces the entire existing list.

Example Request

curl -ks -X PUT -H 'Content-Type: application/json' \
     -H 'X-Auth-Token: gAAAAA<...>' \
     -d '{
  "port": {
    "name": "dhcp-port",
    "device_owner": "network:dhcp",
    "device_id": "dhcpe52a9a47-9f6a-5406-9193-a4d7333f9889-f858b8d1-e66b-4a48-bc2e-3f16483b1b58"
  }
}' \
https://<node_IP_addr>:9696/v2.0/ports/c85ae844-9ff5-4866-97da-546c3bf0144b

Response

Response Parameters

If successful the API returns a single updated port object with all current attributes.

portobjectrequired

Port object wrapper.

idstringrequired

Port ID.

namestringrequired

Port name.

network_idstringrequired

ID of the attached network.

tenant_idstringrequired

Project ID (legacy field).

project_idstringrequired

Owning project ID.

mac_addressstringrequired

MAC address (may be overridden for direct-physical).

admin_state_upbooleanrequired

Administrative state.

statusstringrequired

Port status: ACTIVE, DOWN, BUILD, or ERROR.

device_idstringrequired

ID of the attached device.

device_ownerstringrequired

Entity type using the port.

fixed_ipsarrayrequired

List of {subnet_id, ip_address} for the port.

allowed_address_pairsarrayrequired

Allowed address pairs.

extra_dhcp_optsarrayrequired

Extra DHCP option objects.

security_groupsarrayrequired

Security group IDs.

descriptionstringrequired

Description.

binding:vnic_typestringrequired

vNIC type.

binding:profileobjectrequired

Backend-specific VIF info ( {} if none ).

binding:host_idstringrequired

Host ID where the port resides.

binding:vif_typestringrequired

Mechanism driver type or unbound / binding_failed.

binding:vif_detailsobjectrequired

Additional info (port_filter, ovs_hybrid_plug, etc.).

port_security_enabledbooleanrequired

Whether port security is enabled.

qos_policy_idstringrequired

QoS policy applied directly (or null).

qos_network_policy_idstringrequired

QoS policy of the network (or null).

resource_requestobject

Placement resource groups / traits requested.

tagsarrayrequired

Tag list.

created_atstringrequired

Creation timestamp (ISO 8601).

updated_atstringrequired

Last update timestamp (ISO 8601) or null.

revision_numberintegerrequired

Revision number.

ip_allocationstringrequired

Allocation mode (immediate, deferred, or none).

dns_assignmentobjectrequired

Internal DNS assignment (hostname, ip_address, fqdn).

dns_domainstringrequired

DNS domain.

dns_namestringrequired

DNS name.

hintsobjectrequired

OVS Userspace Tx packet steering hints (admin-only) if present.

numa_affinity_policystring

NUMA affinity policy.

propagate_uplink_statusbooleanrequired

Uplink status propagation flag.

mac_learning_enabledboolean

Whether MAC learning is enabled.

port_trusted_vifbooleanrequired

Trusted VIF status.

data_plane_statusstringrequired

Underlying data plane status if reported.

Status Codes

Success

Code	Reason
200 - OK	Request was successful.

Error

Code	Reason
400 - Bad Request	Some content in the request was invalid.
401 - Unauthorized	User must authenticate before making a request.
403 - Forbidden	Policy does not allow current user to do this operation.
404 - Not Found	The requested resource could not be found.
409 - Conflict	Operation conflicted with another operation on this resource.
412 - Precondition Failed	A request precondition (header) was not met.

Example Response

Response body

{
    "port": {
        "id": "2d74fa0c-3e43-4fd9-a234-cbb4996cc684",
        "name": "dhcp-port",
        "network_id": "f858b8d1-e66b-4a48-bc2e-3f16483b1b58",
        "tenant_id": "f33507157a634f1cac71e06a70fb558e",
        "mac_address": "fa:16:3e:7f:ae:b2",
        "admin_state_up": true,
        "status": "DOWN",
        "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.12"
            }
        ],
        "allowed_address_pairs": [],
        "extra_dhcp_opts": [],
        "security_groups": [
            "e1c1aa83-7302-4493-9cf4-43c2407e8074"
        ],
        "description": "",
        "binding:vnic_type": "normal",
        "port_security_enabled": true,
        "qos_policy_id": null,
        "qos_network_policy_id": "dfc42ced-02c8-4b1f-bbe6-14cc014f259d",
        "tags": [],
        "created_at": "2025-10-08T08:05:12Z",
        "updated_at": "2025-10-08T08:21:32Z",
        "revision_number": 3,
        "project_id": "f33507157a634f1cac71e06a70fb558e"
    }
}

See Also

• Listing Network Ports
• Create Network Port
• Show Network Port Details