Update Network Port

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

PUT /v2.0/ports/{port_id}

Path Parameters

Name	In	Type	Description
port_id	path	string	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

Name	In	Type	Description
port	body	object	Wrapper object containing the fields to update. Provide only the fields you want to change.
name (Optional)	body	string	Human‑readable name of the port.
description (Optional)	body	string	Human‑readable description (empty string by default).
admin_state_up (Optional)	body	boolean	Administrative state: up (true) or down (false).
device_id (Optional)	body	string	ID of the device (server, router, etc.) using this port.
device_owner (Optional)	body	string	Entity type using the port (compute:nova, network:dhcp, network:router_interface, etc.).
security_groups (Optional)	body	array	List of security group IDs to apply. Replaces the existing list.
fixed_ips (Optional)	body	array	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_pairs (Optional)	body	array	List of objects each with ip_address (required) and optional mac_address. Replaces existing list.
extra_dhcp_opts (Optional)	body	array	List of DHCP option objects (opt_name, opt_value). Replaces existing list.
port_security_enabled (Optional)	body	boolean	Enable/disable security group & anti‑spoofing enforcement.
qos_policy_id (Optional)	body	string	QoS policy to associate (or null to clear).
binding:host_id (Optional)	body	string	Host ID where the port resides. Typically set by the system / scheduler; admin override only.
binding:profile (Optional)	body	object	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_type (Optional)	body	string	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_address (Optional)	body	string	Port MAC address. Usually immutable after creation except in specific binding scenarios (e.g. with direct-physical and device_mac_address).
dns_domain (Optional)	body	string	DNS domain to associate.
dns_name (Optional)	body	string	DNS name (hostname) to associate.
hints (Optional)	body	object	Admin-only mechanism driver hints (e.g. {"openvswitch": {"other_config": {"tx-steering": "hash"}}}). Max length 4095 chars serialized.
numa_affinity_policy (Optional)	body	string	NUMA affinity policy: none, required, preferred, or legacy.
propagate_uplink_status (Optional)	body	boolean	Whether uplink status propagation is enabled.
mac_learning_enabled (Optional)	body	boolean	Enable MAC learning on the port.
port_trusted_vif (Optional)	body	boolean	Trusted VIF status. Reflected within binding:profile.
allowed_address_pairs[*].ip_address	body	string	IP address or CIDR.
allowed_address_pairs[*].mac_address (Optional)	body	string	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.

Name	In	Type	Description
port	body	object	Port object wrapper.
id	body	string	Port ID.
name	body	string	Port name.
network_id	body	string	ID of the attached network.
tenant_id	body	string	Project ID (legacy field).
project_id	body	string	Owning project ID.
mac_address	body	string	MAC address (may be overridden for direct-physical).
admin_state_up	body	boolean	Administrative state.
status	body	string	Port status: ACTIVE, DOWN, BUILD, or ERROR.
device_id	body	string	ID of the attached device.
device_owner	body	string	Entity type using the port.
fixed_ips	body	array	List of {subnet_id, ip_address} for the port.
allowed_address_pairs	body	array	Allowed address pairs.
extra_dhcp_opts	body	array	Extra DHCP option objects.
security_groups	body	array	Security group IDs.
description	body	string	Description.
binding:vnic_type	body	string	vNIC type.
binding:profile	body	object	Backend-specific VIF info ( {} if none ).
binding:host_id	body	string	Host ID where the port resides.
binding:vif_type	body	string	Mechanism driver type or unbound / binding_failed.
binding:vif_details	body	object	Additional info (port_filter, ovs_hybrid_plug, etc.).
port_security_enabled	body	boolean	Whether port security is enabled.
qos_policy_id	body	string	QoS policy applied directly (or null).
qos_network_policy_id	body	string	QoS policy of the network (or null).
resource_request (Optional)	body	object	Placement resource groups / traits requested.
tags	body	array	Tag list.
created_at	body	string	Creation timestamp (ISO 8601).
updated_at	body	string	Last update timestamp (ISO 8601) or null.
revision_number	body	integer	Revision number.
ip_allocation	body	string	Allocation mode (immediate, deferred, or none).
dns_assignment	body	object	Internal DNS assignment (hostname, ip_address, fqdn).
dns_domain	body	string	DNS domain.
dns_name	body	string	DNS name.
hints	body	object	OVS Userspace Tx packet steering hints (admin-only) if present.
numa_affinity_policy (Optional)	body	string	NUMA affinity policy.
propagate_uplink_status	body	boolean	Uplink status propagation flag.
mac_learning_enabled (Optional)	body	boolean	Whether MAC learning is enabled.
port_trusted_vif	body	boolean	Trusted VIF status.
data_plane_status	body	string	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

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