All Products
Search
Document Center

Server Load Balancer:SetLoadBalancerUDPListenerAttribute

Last Updated:May 12, 2026

Modify the configuration of the UDP listener.

Operation description

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

  • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

  • API: The API that you can call to perform the action.

  • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

  • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

    • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

    • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

  • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

  • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

slb:SetLoadBalancerUDPListenerAttribute

update

*acl

acs:slb:{#regionId}:{#accountId}:acl/{#aclId}

*loadbalancer

acs:slb:{#regionId}:{#accountId}:loadbalancer/{#loadbalancerId}

  • slb:tag

  • slb:tag

None

Request parameters

Parameter

Type

Required

Description

Example

RegionId

string

No

The region ID of the Classic Load Balancer (CLB) instance.

You can find the region ID by calling the DescribeRegions operation.

cn-hangzhou

LoadBalancerId

string

Yes

The ID of the CLB instance.

lb-bp1rtfnodmywb43ecu4sf-c****

ListenerPort

integer

Yes

The frontend port used by the CLB instance.

Valid values: 1 to 65535.

80

Bandwidth

integer

No

The peak bandwidth of the listener. Unit: Mbit/s. Valid values:

  • -1: For an Internet-facing pay-by-traffic CLB instance, set the value to -1. This specifies that the bandwidth of the listener is unlimited.

  • 1 to 5120: For an Internet-facing pay-by-bandwidth CLB instance, you can specify the peak bandwidth for each listener. The sum of the peak bandwidth values of all listeners cannot exceed the peak bandwidth of the CLB instance.

-1

Scheduler

string

No

The scheduling algorithm. Valid values:

  • wrr: Backend servers with higher weights receive more requests than those with lower weights. If backend servers have the same weight, the backend server that has fewer connections receives more requests.

  • rr: Requests are distributed to backend servers in sequence.

  • sch: Source IP hashing. Requests from the same source IP address are distributed to the same backend server.

  • tch: Four-tuple hashing. Requests from the same four-tuple (source IP address, destination IP address, source port, and destination port) are distributed to the same backend server.

  • qch: QUIC ID hashing. Requests that have the same QUIC ID are distributed to the same backend server.

Note
  • Only performance-guaranteed instances support the sch, tch, and qch scheduling algorithms.

  • You cannot change the scheduling algorithm from wrr or rr to a consistent hashing algorithm. You also cannot change a consistent hashing algorithm to another one.

wrr

HealthyThreshold

integer

No

The number of consecutive successful health checks that must occur before a backend server can be declared healthy (from unhealthy).

Valid values: 1 to 10.

4

UnhealthyThreshold

integer

No

The number of consecutive failed health checks that must occur before a backend server can be declared unhealthy (from healthy).

Valid values: 1 to 10.

4

HealthCheckConnectTimeout

integer

No

The timeout period of a health check response. If a backend ECS instance does not send an expected response within the specified timeout period, the health check fails. Unit: seconds.

Valid values: 1 to 300.

Note

If the value of the HealthCheckConnectTimeout parameter is smaller than that of the HealthCheckInterval parameter, the HealthCheckConnectTimeout parameter is invalid and the timeout period is specified by the HealthCheckInterval parameter.

100

HealthCheckConnectPort

integer

No

The port used for health checks.

Valid values: 1 to 65535.

80

HealthCheckInterval

integer

No

The interval between two consecutive health checks. Unit: seconds.

Valid values: 1 to 50.

5

healthCheckReq

string

No

The request string for UDP health checks. The string must be 1 to 64 characters in length and can contain only letters and digits.

hello

healthCheckExp

string

No

The response string for UDP health checks. The string must be 1 to 64 characters in length and can contain only letters and digits.

ok

VServerGroup

string

No

Specifies whether to use a vServer group. Valid values:

  • on: yes

  • off: no

Note

You can set the value of this parameter to on for only one of the VserverGroup and MasterSlaveServerGroup parameters.

on

VServerGroupId

string

No

The ID of the vServer group.

rsp-cige6****

MasterSlaveServerGroupId

string

No

The ID of the primary/secondary server group.

Note

You can specify only one of VServerGroupId and MasterSlaveServerGroupId.

rsp-0bfuc****

MasterSlaveServerGroup

string

No

Specifies whether to use a primary/secondary server group. Valid values:

  • on: yes

  • off: no

Note

You can set the value to on for only one of the VserverGroup and MasterSlaveServerGroup parameters.

on

AclId

string

No

The ID of the network access control list (ACL) that is associated with the listener.

Note

This parameter is required if the AclStatus parameter is set to on.

off

AclType

string

No

The type of the network ACL. Valid values:

  • white: a whitelist. Only requests from the IP addresses or CIDR blocks in the network ACL are forwarded. Whitelists are suitable for scenarios where you want to allow access from only specific IP addresses. If you enable a whitelist, but do not add an IP address to the network ACL, the CLB listener forwards all requests.

    If whitelist access is enabled but no IP addresses are added to the access control list, the load balancer listener forwards all requests.

  • black: a blacklist. All requests from the IP addresses or CIDR blocks in the network ACL are denied. Blacklists are suitable for scenarios where you want to deny access from specific IP addresses. If you enable a blacklist, but do not add an IP address to the network ACL, the CLB listener forwards all requests.

    If blacklist access control is enabled but no IP addresses are added to the access control list, the load balancer listener forwards all requests.

Note

This parameter is valid only when the AclStatus parameter is set to on.

white

AclStatus

string

No

Specifies whether to enable access control. Valid values:

  • on: yes

  • off: no

off

Description

string

No

The name of the listener.

The name must be 1 to 256 characters in length, and can contain letters, digits, Chinese characters, and the following special characters: - / . _.

udp_80

ProxyProtocolV2Enabled

boolean

No

Specifies whether to use the Proxy Protocol to pass client IP addresses to backend servers. Valid values:

  • true: yes

  • false (default): no

false

HealthCheckSwitch

string

No

Specifies whether to enable health checks. Valid values:

  • on (default): Enabled.

  • off: Disabled.

on

DryRun

boolean

No

Response elements

Element

Type

Description

Example

object

RequestId

string

The ID of the request.

CEF72CEB-54B6-4AE8-B225-F876FF7BA984

Examples

Success response

JSON format

{
  "RequestId": "CEF72CEB-54B6-4AE8-B225-F876FF7BA984"
}

Error codes

HTTP status code

Error code

Error message

Description

400

InvalidParameterValue.SpecNotSupport

The loadBalancer of shared spec does not support the parameter value, %s.

400

OperationNotSupport.Acl

The cloud box instance does not support acl.

400

InvalidParameterValue.RegionNotSupport

The region does not support the parameter value, %s.

400

IpVersionConflict

The ip version of this LoadBalancer and the Acl is conflict.

400

InvalidParameterValue.ZoneNotSupport

The zone does not support the parameter value, %s.

400

OperationFailed.ServerGroupInUse

The VServerGroup or MasterSlaveServerGroup can not be close for this listener.

400

InvalidParam.VServerGroupId

The specified VServerGroupId is invalid.

400

MissingParam.HealthCheckConnectPort

The parameter HealthCheckConnectPort is required.

400

InvalidParam.ListenerPort

The specified ListenerPort is invalid.

400

InvalidParam.StartPort

The specified StartPort is invalid.

400

InvalidParamSize.PortRange

The size of param PortRange is invalid.

400

InvalidParam.EndPort

The specified EndPort is invalid.

400

InvalidParam.PortRange

The specified PortRange is invalid.

400

Duplicated.AclEntry

%s.

%s

400

InvalidParamLength.HealthCheckReq

The length of the parameter HealthCheckReq is invalid.

400

InvalidParamLength.HealthCheckExp

The length of the parameter HealthCheckExp is invalid.

400

InvalidParam.HealthCheckReq

The param HealthCheckReq is invalid.

400

InvalidParam.HealthCheckExp

The param HealthCheckExp is invalid.

400

ResourceNotFound.VServerGroup

%s.

400

IllegalParam.FailoverThreshold

The parameter FailoverThreshold is illegal.

400

IllegalParam.FailoverStrategy

The parameter FailoverStrategy is illegal.

400

InvalidParameter.ZoneNotSupport

The zone does not support the parameter %s.

400

MasterSlaveServerConflict

The servers are conflict for MasterSlaveGroup.

400

MissingParam.VServerGroupId

The parameter VServerGroupId is missing.

400

VipNotSupportQuicVersion

The listener does not support the parameter of QuicVersion.

400

IllegalParam.HealthCheckType

The param of HealthCheckType is illegal.

400

IllegalParam.HealthCheckMethod

The param of HealthCheckMethod is illegal.

400

IllegalParam.HealthCheck

The param of HealthCheck is illegal.

400

OperationDenied.MasterSlaveGroupLogEnabled

The operation is denied because of MasterSlaveGroupLogEnabled.

400

OperationDenied.OnlyIpv4SlbSupport

The operation is not allowed because of OnlyIpv4SlbSupport.

400

OperationDenied.FullNatModeNotAllowed

The operation is not allowed because of FullNatModeNotAllowed.

400

SpecNotSupportParameter

The instance with share spec does not support FullNatEnabled parameter.

400

Abs.VServerGroupIdAndMasterSlaveServerGroupId.MissMatch

Virtual service group ID or master slave server group ID is missing. Please check the input parameters.

400

AclListenerOverLimit

This acl has reached the limit of binding to listeners.

400

QuotaLimitExceeds.AclAttachedToListener

The number of Acl bound listeners has reached the quota limit

400

QuotaLimitExceeds.TotalAclEntry

The number of Acl entries has reached the quota limit.

400

QuotaLimitExceeds.AclListenerOverLimit

This acl has reached the limit of binding to listeners.

400

DryRunOperation

Request validation has been passed with DryRun flag set.

Request validation has been passed with DryRun flag set.

403

UnauthorizedRegion

The specified region of is not authorized.

The specified region of is not authorized.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.