Creates a TCP listener.

Note Newly created listeners are in the stopped state. After a listener is created, you must call the StartLoadBalancerListener operation to start the listener. This way, the listener can forward network traffic.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes CreateLoadBalancerTCPListener

The operation that you want to perform.

Set the value to CreateLoadBalancerTCPListener.

Bandwidth Integer Yes -1

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

  • -1: For a pay-by-data-transfer Internet-facing Classic Load Balancer (CLB) instance, set the value to -1. This indicates that the maximum bandwidth value is unlimited.
  • 1 to 5120: For a pay-by-bandwidth Internet-facing CLB instance, you can specify a maximum bandwidth value for each listener. The sum of maximum bandwidth values that you set for all listeners cannot exceed the maximum bandwidth value of the CLB instance.
ListenerPort Integer Yes 80

The frontend port that is used by the CLB instance.

Valid values: 1 to 65535.

LoadBalancerId String Yes lb-bp1b6c719dfa08ex****

The ID of the CLB instance.

RegionId String Yes cn-hangzhou

The region ID of the CLB instance.

You can query region IDs from the Regions and zones list or by calling the DescribeRegions operation.

BackendServerPort Integer No 80

The backend port that is used by the CLB instance.

Valid values: 1 to 65535.

If the VServerGroupId parameter is not set, this parameter is required.

Scheduler String No wrr

The scheduling algorithm. Valid values:

  • wrr (default): Backend servers with higher weights receive more requests than backend servers with lower weights.
  • rr: Requests are sequentially distributed to backend servers.
  • sch: specifies consistent hashing that is based on source IP addresses. Requests from the same source IP address are distributed to the same backend server.
  • tch: specifies consistent hashing that is based on four factors: source IP address, destination IP address, source port, and destination port. Requests that contain the same information based on the four factors are distributed to the same backend server.
Note Only high-performance CLB instances support sch and tch.
PersistenceTimeout Integer No 0

The timeout period of session persistence. Unit: seconds.

Valid values: 0 to 3600.

Default value: 0. If you set the value to 0, session persistence is disabled.

EstablishedTimeout Integer No 500

The timeout period of connections. Unit: seconds.

Value values: 10 to 900.

HealthyThreshold Integer No 4

The number of consecutive health check successes before a backend server is declared healthy (from fail to success).

Valid values: 2 to 10.

UnhealthyThreshold Integer No 4

The number of consecutive health check failures before a backend server is declared unhealthy (from success to fail).

Valid values: 2 to 10.

HealthCheckConnectTimeout Integer No 100

The timeout period of a health check response. Unit: seconds.

Valid values: 1 to 300.

Default value: 5.

HealthCheckConnectPort Integer No 80

The port that is used for health checks.

Valid values: 1 to 65535.

If this parameter is not set, the port specified by BackendServerPort is used for health checks.

healthCheckInterval Integer No 3

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

Valid values: 1 to 50.

HealthCheckDomain String No 172.XX.XX.6

The domain name used for health checks. Valid values:

  • $_ip: the private IP address of a backend server. If you do not set this parameter or set the parameter to $_ip, CLB uses the private IP address of each backend server as the domain name for health checks.
  • domain: The domain name must be 1 to 80 characters in length, and can contain letters, digits, periods (.), and hyphens (-).
HealthCheckURI String No /test/index.html

The uniform resource identifier (URI) that is used for health checks. The URI must be 1 to 80 characters in length, and can contain letters, digits, hyphens (-), forward slashes (/), periods (.), percent signs (%), number signs (#), and ampersands (&). The URI must start with a forward slash (/) but cannot be a single forward slash (/).

You can set this parameter when the TCP listener requires HTTP health checks. If you do not set this parameter, TCP health checks are performed.

HealthCheckHttpCode String No http_2xx,http_3xx

The HTTP status code that indicates a successful health check. Separate multiple HTTP status codes with commas (,).

Valid values:

  • http_2xx(default)
  • http_3xx
  • http_4xx
  • http_5xx
HealthCheckType String No tcp

The type of health check.

Valid values:

  • tcp (default)
  • http
VServerGroupId String No rsp-cige6j****

The ID of the vServer group.

MasterSlaveServerGroupId String No rsp-0bfucw****

The ID of the primary/secondary server group.

Note You cannot specify the vServer group ID and primary/secondary server group ID at the same time.
AclId String No 1323

The ID of the access control list (ACL) to be associated with the listener.

Note If AclStatus is set to on, this parameter is required.
AclType String No black

The type of ACL.

  • white: a whitelist. Only requests from the IP addresses or CIDR blocks in the ACL are forwarded. Whitelists apply to scenarios where you want to allow only specific IP addresses to access an application.

    Your business may be adversely affected if the whitelist is not set properly.

    After a whitelist is configured, only IP addresses in the whitelist can access the CLB listener. If you enable a whitelist but the whitelist does not contain an IP address, the listener forwards all requests.

  • black: a blacklist. All requests from the IP addresses or CIDR blocks in the ACL are rejected. Blacklists apply to scenarios where you want to block access from specified IP addresses to an application.

    If you enable a blacklist but the blacklist does not contain an IP address, the CLB listener forwards all requests.

Note If AclStatus is set to on, this parameter is required.
AclStatus String No off

Specifies whether to enable the ACL feature. Default value: off.

Valid values:

  • on
  • off (default)
Description String No CreateListeners

The description of the listener.

ConnectionDrain String No off

Specifies whether to enable connection draining. Valid values:

  • on: yes
  • off: no
ConnectionDrainTimeout Integer No 300

The timeout period for connection draining. Unit: seconds.

Valid values: 10 to 900.

Note If ConnectionDrain is set to on, this parameter is required.

Response parameters

Parameter Type Example Description
RequestId String CEF72CEB-54B6-4AE8-B225-F876FF7BA984

The ID of the request.

Examples

Sample requests

http(s)://[Endpoint]/?Action=CreateLoadBalancerTCPListener
&Bandwidth=-1
&ListenerPort=80
&LoadBalancerId=lb-bp1b6c719dfa08ex****
&<Common request parameters>

Sample success responses

XML format 

<CreateLoadBalancerTCPListenerResponse>
  <RequestId>CEF72CEB-54B6-4AE8-B225-F876FF7BA984</RequestId>
</CreateLoadBalancerTCPListenerResponse>

JSON format 

null

Error codes

HttpCode Error code Error message Description
400 Abs.VServerGroupIdAndMasterSlaveServerGroupId.MissMatch The parameters VServerGroupId or MasterSlaveServerGroupId miss match. The error message returned because the VServerGroupId parameter or the MasterSlaveServerGroupId parameter does not match.
400 LbNotSupportTcpssl You cannot create a TCP SSL type listener for the specified load balancer. The error message returned because the specified instance does not allow you to create TCP listeners.
400 LbSupportTcpsslOnly The specified load balancer supports TCP SSL type listener only. The error message returned because the specified instance allows you to create only TCP listeners.
400 ListenerNotSupportRule You cannot create a rule for the specified listener. The error message returned because the specified listener does not allow you to create forwarding rules.
400 Mismatch.SlbSpecTypeAndListenerProtocol The SlbSpecType and ListenerProtocol are mismatched. The error message returned because the specified instance type and listener type do not match.
400 OperationDenied.FullNatModeNotAllowed The operation is not allowed because of FullNatModeNotAllowed. The error message returned because the full NAT mode is not supported.
400 OperationDenied.OnlyIpv4SlbSupport The operation is not allowed because of OnlyIpv4SlbSupport. The error message returned because only IPv4 instances support the full NAT mode.
400 SpecNotSupportParameter The instance with share spec does not support FullNatEnabled parameter. The error message returned because resource-shared instances do not support the FullNatEnabled parameter.

For a list of error codes, visit the API Error Center.