Updated on 2024-04-18 GMT+08:00

Updating a Port

Function

This API is used to update a port.

URI

PUT /v1/{project_id}/ports/{port_id}

Table 1 describes the parameters.
Table 1 Parameter description

Name

Mandatory

Description

port_id

Yes

Specifies the port ID that uniquely identifies the port.

project_id

Yes

Specifies the project ID. For details about how to obtain a project ID, see Obtaining a Project ID.

Request Parameters

Name

Mandatory

Type

Description

port

Yes

port object

Specifies the port objects. For details, see Table 2.

Table 2 Description of the port field

Name

Mandatory

Type

Description

name

No

String

  • Specifies the port name.
  • The value can contain up to 255 characters. This parameter is left blank by default.

security_groups

No

Array of strings

Specifies the UUID of the security group. This is an extended attribute.

allowed_address_pairs

No

Array of allowed_address_pairs objects

  • Specifies the IP address and MAC address pair. An address pair consists of an IP address and a MAC address. For details, see parameter allow_address_pair in Table 3.
  • Constraints:
    • The IP address cannot be 0.0.0.0/0.
    • Configure a dedicated security group for the port if the parameter allowed_address_pairs has a large CIDR block (subnet mask less than 24).
    • If the value of allowed_address_pairs is 1.1.1.1/0, the source/destination check is disabled.
    • To assign a virtual IP address to an ECS, the IP address configured in allowed_address_pairs must be an existing ECS NIC IP address. Otherwise, the virtual IP address cannot be used for communication.
    • Set allowed_address_pairs of the cloud server to 1.1.1.1/0.

extra_dhcp_opts

No

Array of extra_dhcp_opt objects

Specifies the extended option (extended attribute) of DHCP. For details, see Table 4.

Table 3 allowed_address_pairs objects

Name

Mandatory

Type

Description

ip_address

Yes

String

  • Specifies the IP address.
  • You cannot set it to 0.0.0.0/0.
  • Configure a dedicated security group for the port if the parameter allowed_address_pairs has a large CIDR block (subnet mask less than 24).
  • If the value of allowed_address_pairs is 1.1.1.1/0, the source/destination check is disabled.
  • Set allowed_address_pairs of the cloud server to 1.1.1.1/0.
  • If the value of parameter allowed_address_pairs is specified, parameter ip_address is mandatory.

mac_address

No

String

Specifies the MAC address.

Table 4 extra_dhcp_opt object

Name

Mandatory

Type

Description

opt_name

No

String

Specifies the name of the DHCP option. The value of this parameter can only be 51, indicating the DHCP lease time.

opt_value

No

String

Specifies the value of the DHCP option.

If the value of opt_name is 51, the value format of opt_value is Xh, indicating that the DHCP lease time is X hours.

The value of X is -1 or from 1 to 30000. If the value is -1, the DHCP lease time is infinite.

Example Request

  • Change the name of the port whose ID is 7204e0da-40de-4207-a536-6f59b84f6f0e to abc.
    PUT https://{Endpoint}/v1/{project_id}/ports/7204e0da-40de-4207-a536-6f59b84f6f0e
     
    {
        "port": {
            "name": "adc"
        }
    }

Response Parameters

Table 5 Response parameter

Name

Type

Description

port

port object

Specifies the port objects. For details, see Table 6.

Table 6 Description of the port field

Parameter

Type

Description

id

String

Specifies the port ID that uniquely identifies the port.

name

String

  • Specifies the port name.
  • The value can contain up to 255 characters. This parameter is left blank by default.

network_id

String

  • Specifies the ID of the network that the port belongs to.
  • The network ID must exist.

admin_state_up

Boolean

  • Specifies the administrative state of the port.
  • The default value is true.

mac_address

String

  • Specifies the port MAC address.
  • The MAC address is assigned by the system not specified by users.

fixed_ips

Array of fixed_ip objects

  • Specifies the port IP address. For example, the value is "fixed_ips": [{"subnet_id": "4dc70db6-cb7f-4200-9790-a6a910776bba", "ip_address": "192.169.25.79"}]. For details, see Table 7.
  • In IPv4 scenarios, a port supports only one fixed IP address that cannot be changed. In IPv6 scenarios, a port supports a maximum of two fixed IP addresses that cannot be changed.

device_id

String

  • Specifies the ID of the device that the port belongs to.
  • The system automatically sets this parameter, and you are not allowed to configure or change the parameter value.

device_owner

String

  • Specifies the owner of the device to which the port belongs, which can be a DHCP server, router, load balancer, or Nova.
  • The value can be network:dhcp, network:router_interface_distributed, compute:xxx, neutron:VIP_PORT, neutron:LOADBALANCERV2, neutron:LOADBALANCERV3, network:endpoint_interface, network:nat_gateway, or network:ucmp. (In value compute:xxx, xxx specifies the AZ name, for example, compute:aa-bb-cc indicates that the private IP address is used by an ECS in the aa-bb-cc AZ).
  • This parameter value cannot be updated. You can only set device_owner to neutron:VIP_PORT for a virtual IP address port during port creation. If this parameter is not left blank, the port can only be deleted when this parameter value is neutron:VIP_PORT.

tenant_id

String

Specifies the project ID.

status

String

  • Specifies the port status. The status of a HANA SR-IOV VM port is always DOWN.
  • The value can be ACTIVE, BUILD, or DOWN.

security_groups

Array of strings

Specifies the security group UUID (extended attribute).

allowed_address_pairs

Array of allowed_address_pairs objects

  • Specifies the IP address and MAC address pair. An address pair consists of an IP address and a MAC address. For details, see Table 8.
  • The IP address cannot be 0.0.0.0/0.
  • Configure a dedicated security group for the port if the parameter allowed_address_pairs has a large CIDR block (subnet mask less than 24).
  • If the value of allowed_address_pairs is 1.1.1.1/0, the source/destination check is disabled.
  • Set allowed_address_pairs of the cloud server to 1.1.1.1/0.

extra_dhcp_opts

Array of extra_dhcp_opt objects

Specifies the extended option (extended attribute) of DHCP. For details, see Table 9.

binding:vif_details

binding:vif_details object

For details, see Table 10.

binding:profile

Object

Specifies the user-defined settings. This is an extended attribute.

Note:

  • The internal_elb field is in boolean type and is available to common tenants. Set the value of this parameter to true only when you assign a virtual IP address to an internal network load balancer. Common tenants do not have the permission to change the value of this field, which is maintained by the system.

    Example:

    {"internal_elb": true}

  • The disable_security_groups field is in boolean type and is available to common tenants. The default value is false. In high-performance communication scenarios, you can set the parameter value to true, which makes this parameter to be available to common tenants. You can specify this parameter when creating a port. Currently, the value of this parameter can only be set to true.

    Example:

    {"disable_security_groups": true }

    Currently, the value can only be set to true. When the value is set to true, the FWaaS function does not take effect.

binding:vnic_type

String

  • Specifies the type of the bound vNIC.
  • The value can be normal or direct.
  • normal indicates software switching. direct indicates SR-IOV PCIe passthrough, which is not supported.

instance_id

String

  • Specifies the ID of the instance to which the port belongs, for example, RDS instance ID.
  • The system automatically sets this parameter, and you are not allowed to configure or change the parameter value.

instance_type

String

  • Specifies the type of the instance to which the port belongs, for example, RDS.
  • The system automatically sets this parameter, and you are not allowed to configure or change the parameter value.

port_security_enabled

Boolean

  • Specifies whether the security option is enabled for the port. If the option is not enabled, the security group and DHCP snooping do not take effect.

ipv6_bandwidth_id

String

  • Specifies the ID of the shared bandwidth associated with the IPv6 NIC.
  • This parameter is displayed only when the IPv6 NIC is associated with a shared bandwidth.
Table 7 fixed_ip object

Name

Type

Description

subnet_id

String

  • Specifies the subnet ID.

    If you use the management console, the value of this parameter is the IPv4 Subnet ID or IPv6 Subnet ID value.

  • You cannot change the parameter value.

ip_address

String

Specifies the port IP address.

Table 8 allowed_address_pairs objects

Name

Type

Description

ip_address

String

  • Specifies the IP address.
  • You cannot set it to 0.0.0.0/0.
  • Configure a dedicated security group for the port if the parameter allowed_address_pairs has a large CIDR block (subnet mask less than 24).
  • If the value of allowed_address_pairs is 1.1.1.1/0, the source/destination check is disabled.
  • Set allowed_address_pairs of the cloud server to 1.1.1.1/0.

mac_address

String

Specifies the MAC address.

Table 9 extra_dhcp_opt object

Name

Type

Description

opt_name

String

Specifies the name of the DHCP option. The value of this parameter can only be 51, indicating the DHCP lease time.

opt_value

String

Specifies the value of the DHCP option.

If the value of opt_name is 51, the value format of opt_value is Xh, indicating that the DHCP lease time is X hours.

The value of X is -1 or from 1 to 30000. If the value is -1, the DHCP lease time is infinite.

Table 10 binding:vif_details object

Name

Type

Description

primary_interface

Boolean

If the value is true, this is the primary NIC.

port_filter

Boolean

Specifies the port used for filtering in security groups to protect against MAC or IP spoofing.

ovs_hybrid_plug

Boolean

Specifies that OVS hybrid plug should be used by Nova APIs.

Example Response

{
    "port": {
        "id": "7204e0da-40de-4207-a536-6f59b84f6f0e",
        "name": "adc",
        "status": "DOWN",
        "admin_state_up": "true",
        "fixed_ips": [
            {
                "subnet_id": "689156ca-038f-4478-b265-fd26aa8bbe31",
                "ip_address": "192.168.0.9"
            }
        ],
        "mac_address": "fa:16:3e:d7:f2:6c",
        "network_id": "b4152e98-e3af-4e49-bb7f-7766e2b5ec63",
        "tenant_id": "caa6cf4337ea47fb823b15709ebe8591",
        "device_id": "",
        "device_owner": "",
        "security_groups": [
            "59b39002-e79b-4bac-8e27-aa884ab1beb6"
        ],
        "extra_dhcp_opts": [],
        "allowed_address_pairs": [],
        "binding:vnic_type": "normal"
    }
}

Status Code

See Status Codes.

Error Code

See Error Codes.