Create TCP, UDP, or TCP/SSL listeners for a Network Load Balancer by using CreateListener - Server Load Balancer - Alibaba Cloud - Server Load Balancer

Creates a TCP, UDP, or TCPSSL listener on a Network Load Balancer (NLB) instance for load balancing.

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

nlb:CreateListener

create

*ServerGroup

acs:nlb:{#regionId}:{#accountId}:servergroup/{#ServerGroupId}

SecurityPolicy

acs:nlb:{#regionId}:{#accountId}:securitypolicy/{#SecurityPolicyId}

*LoadBalancer

acs:nlb:{#regionId}:{#accountId}:loadbalancer/{#LoadbalancerId}

nlb:ListenerProtocol
nlb:SecurityPolicyId

None

Request parameters

Parameter	Type	Required	Description	Example
ListenerProtocol	string	Yes	The listener protocol. Valid values: TCP, UDP, and TCPSSL.	TCP
ListenerPort	integer	Yes	The listener port. Valid values: 0 to 65535. 0: indicates that the all-port feature is used. If you set this parameter to 0, you must configure StartPort and EndPort.	80
ListenerDescription	string	No	The custom name of the listener. The name must be 2 to 256 characters in length, and can contain Chinese characters, English letters, digits, commas (,), periods (.), semicolons (;), forward slashes (/), at signs (@), underscores (_), and hyphens (-).	tcp_80
LoadBalancerId	string	Yes	The instance ID of the Network Load Balancer (NLB) for load balancing.	nlb-83ckzc8d4xlp8o****
ServerGroupId	string	No	The ID of the server group. Note If ListenerProtocol is set to TCP, the listener supports server groups whose backend protocol is TCP or TCP_UDP, but does not support server groups whose backend protocol is UDP. If ListenerProtocol is set to UDP, the listener supports server groups whose backend protocol is UDP or TCP_UDP, but does not support server groups whose backend protocol is TCP. If ListenerProtocol is set to TCPSSL, the listener supports server groups whose backend protocol is TCP and for which client address preservation is disabled. It does not support server groups whose backend protocol is TCP and for which client address preservation is enabled, or server groups whose backend protocol is UDP or TCP_UDP.	sgp-ppdpc14gdm3x4o****
IdleTimeout	integer	No	The idle timeout period for connections. Unit: seconds. If ListenerProtocol is set to TCP or TCPSSL, the idle timeout period ranges from 10 to 900. Default value: 900. If ListenerProtocol is set to UDP, the idle timeout period ranges from 10 to 90. Default value: 90.	900
SecurityPolicyId	string	No	The ID of the security policy. System security policies and custom security policies are supported. Valid values for system policies: tls_cipher_policy_1_0 (default), tls_cipher_policy_1_1, tls_cipher_policy_1_2, tls_cipher_policy_1_2_strict, and tls_cipher_policy_1_2_strict_with_1_3. Custom security policy: Enter the ID of the custom security policy. To create a custom policy, see CreateSecurityPolicy. To query security policies, see ListSecurityPolicy. Note This parameter takes effect only for TCPSSL listeners.	tls_cipher_policy_1_0
CertificateIds	array	No	The information about the server certificates. This parameter takes effect only for TCPSSL listeners. Note You can add only one server certificate.
	string	No	The information about the server certificates. This parameter takes effect only for TCPSSL listeners. Note You can add only one server certificate.	123157******
CaCertificateIds	array	No	The list of CA certificates. This parameter takes effect only for TCPSSL listeners. Note You can add only one CA certificate.
	string	No	The list of CA certificates. This parameter takes effect only for TCPSSL listeners. Note You can add only one CA certificate.	139a00******
CaEnabled	boolean	No	Specifies whether to enable mutual authentication. Valid values: true: enables mutual authentication. false (default): disables mutual authentication.	false
DryRun	boolean	No	Specifies whether to only precheck the request. Valid values: true: prechecks the request without creating the listener. The system checks whether required parameters are specified, the request format is valid, and service limits are met. If the request fails the precheck, the corresponding error is returned. If the request passes the precheck, the `DryRunOperation` error code is returned. false (default): sends the normal request. After the request passes the precheck, an HTTP 2xx status code is returned and the operation is performed.	false
ClientToken	string	No	The client token that is used to ensure the idempotence of the request. You can use the client to generate the value, but you must ensure that it is unique among different requests. The client token can contain only ASCII characters. Note If you do not specify this parameter, the system automatically uses the RequestId of the API request as the ClientToken. The RequestId of each API request is unique.	123e4567-e89b-12d3-a456-426655440000
RegionId	string	No	The region ID of the Network Load Balancer (NLB) instance. You can invoke the DescribeRegions operation to obtain the region ID.	cn-hangzhou
ProxyProtocolEnabled	boolean	No	Specifies whether to use the PROXY protocol to pass the client source IP address to the backend server. Valid values: true: yes. false (default): no.	false
SecSensorEnabled	boolean	No	Specifies whether to enable second-level monitoring. Valid values: true: enables second-level monitoring. false (default): disables second-level monitoring.	false
AlpnEnabled	boolean	No	Specifies whether to enable Application-Layer Protocol Negotiation (ALPN). Valid values: true: enables ALPN. false (default): disables ALPN.	false
AlpnPolicy	string	No	The ALPN policy. Valid values: HTTP1Only: negotiates only the HTTP/1.x protocol. The priority is HTTP/1.1 > HTTP/1.0. HTTP2Only: negotiates only the HTTP/2.0 protocol. HTTP2Optional: prefers the HTTP/1.x protocol but also accepts the HTTP/2.0 protocol. The priority is HTTP/1.1 > HTTP/1.0 > HTTP/2.0. HTTP2Preferred: prefers the HTTP/2.0 protocol but also accepts the HTTP/1.x protocol. The priority is HTTP/2.0 > HTTP/1.1 > HTTP/1.0. Note You must configure this parameter after AlpnEnabled is set to true.	HTTP1Only
StartPort	integer	No	The start port for all-port listening. Valid values: 1 to 65535. Note You must configure this parameter when ListenerPort is set to 0.	244
EndPort	integer	No	The end port for all-port listening. Valid values: 1 to 65535. The end port must be greater than the start port. Note You must configure this parameter when ListenerPort is set to 0.	566
Cps	integer	No	The limit on the number of new connections processed per second by the listener in each zone (VIP). Valid values: 0 to 1000000. 0 indicates that no limit is applied.	100
Mss	integer	No	The maximum segment size (MSS) of TCP packets. Unit: bytes. Valid values: 0 to 1500. 0: indicates that the MSS value of user TCP packets is not modified. Note This parameter is supported only by TCP and TCPSSL listeners.	43
Tag	array<object>	No	The list of tags.
	object	No	The tag.
Key	string	No	The tag key. The key can be up to 64 characters in length, and cannot start with `aliyun` or `acs:`. It cannot contain `http://` or `https://`. Supported characters include letters, digits, underscores (_), periods (.), colons (:), forward slashes (/), equal signs (=), plus signs (+), hyphens (-), and at signs (@). You can add up to 20 tags in a single call.	KeyTest
Value	string	No	The tag value. The value can be up to 128 characters in length, and cannot start with `aliyun` or `acs:`. It cannot contain `http://` or `https://`. Supported characters include letters, digits, underscores (_), periods (.), colons (:), forward slashes (/), equal signs (=), plus signs (+), hyphens (-), and at signs (@). You can add up to 20 tags in a single call.	Test
ProxyProtocolV2Config	object	No	The configuration for passing the VpcId, PrivateLinkEpId, and PrivateLinkEpsId information to the backend server by using the PROXY protocol.
Ppv2VpcIdEnabled	boolean	No	Specifies whether to use the PROXY protocol to pass the VpcId to the backend server. Valid values: true: yes. false (default): no.	false
Ppv2PrivateLinkEpIdEnabled	boolean	No	Specifies whether to use the PROXY protocol to pass the Ppv2PrivateLinkEpId to the backend server. Valid values: true: yes. false (default): no.	false
Ppv2PrivateLinkEpsIdEnabled	boolean	No	Specifies whether to use the PROXY protocol to pass the PrivateLinkEpsId to the backend server. Valid values: true: yes. false (default): no.	false

Response elements

Element	Type	Description	Example
	object	RpcResponse
RequestId	string	The request ID.	CEF72CEB-54B6-4AE8-B225-F876FF7BA984
ListenerId	string	The listener ID.	lsn-bp1bpn0kn908w4nbw****@80
JobId	string	The ID of the asynchronous task.	72dcd26b-f12d-4c27-b3af-18f6aed5****

Examples

Success response

JSON format

{
  "RequestId": "CEF72CEB-54B6-4AE8-B225-F876FF7BA984",
  "ListenerId": "lsn-bp1bpn0kn908w4nbw****@80",
  "JobId": "72dcd26b-f12d-4c27-b3af-18f6aed5****"
}

Error codes

HTTP status code	Error code	Error message	Description
400	Conflict.Port	The Port [%s] is conflict.	The specified port conflicts with an existing port
400	IllegalParam.MssConflictWithUdpAndGeneve	The param of MssConflictWithUdpAndGeneve is illegal.	When the Mss value is not null, the listenerProtocol cannot be udp or GENEVE.
400	QuotaExceeded.%s	The quota of %s is exceeded, usage %s/%s.	The quota for %s has been exceeded. Used: %s/%s.
400	SystemBusy	System is busy, please try again later.	The system is busy. Try again later.
400	Mismatch.VpcId	The VpcId is mismatched for %s and %s.	The VpcId is mismatched for %s and %s.
400	ResourceNotEnough.%s	The specified resource of %s is not enough.	The required resource %s is insufficient.
400	Conflict.Lock	The Lock [%s] is conflict.	The specific resource is conflict.
400	IllegalParam.AnyPortListenerConflictWithNonAnyPortServerGroup	The param of AnyPortListenerConflictWithNonAnyPortServerGroup is illegal.	The all-port forwarding setting of the server group must match the anyport setting of the listener. Check the parameters.
400	IncorrectStatus.loadbalancer	The status of loadbalancer [%s] is incorrect.	The current operation cannot be performed on the load balancer as its status is unavailable. Please check if the load balancer is currently undergoing any other operations.
400	ResourceNotFound.Certificate	The specified resource %s is not found.	The resource %s does not exist.
400	IllegalParam.ServerGroupId	The param of ServerGroupId is illegal.	The parameter ServerGroupId is invalid. Check the input parameters.
400	IllegalParam.NonAnyPortListenerConflictWithAnyPortServerGroup	The param of NonAnyPortListenerConflictWithAnyPortServerGroup is illegal.	The listening port configuration conflicts with the full port forwarding switch.
400	MissingParam.Certificate	The param of certificate is missing.	The parameter Certificate is missing.
400	IllegalParam.Port	The param of Port is illegal.	The port range in the request is invalid. Check the input parameters.
400	QuotaExceeded.QuotaInsufficient	The quota of %s is exceeded, usage %s/%s.	The quota is insufficient, currently used %s/%s. Please modify the quota size in the quota center.
400	Mismatch.Protocol	The Protocol is mismatched for %s and %s.	The protocols of the listener and server group do not match.
400	ResourceNotEnough.CaCertificateApiCount	The specified resource of CaCertificateApiCount is not enough.
400	MissingParam.ServerGroupId	The param of ServerGroupId is missing.	The parameter ServerGroupId is missing, please check the input parameters.
400	IllegalParam.ListenerDescription	The parameter ListenerDescription of listener is illegal.	The listener description does not meet the input requirements. Modify the listener description based on the details in the error.
400	DryRunOperation	Request validation has been passed with DryRun flag set.	Request validation has been passed with DryRun flag set.
400	IllegalParam.IdleTimeout	The param of IdleTimeout is illegal.	The parameter connection idle timeout configuration is invalid.
400	MissingParam.%s	The parameter of %s is missing.	The parameter %s is missing. Check the input parameters.
400	IllegalParam	The param of %s is illegal.	The input parameters contain invalid values. Check the input.
400	IllegalParamSize.certificateIds	The param size of certificateIds or caCertificateIds is illegal.	you can only have one certificate id. check whether the id is entered repeatedly.
400	DuplicatedParam.listener	The param of any port listener is duplicated.	Only one listener of the anyport type can be created. Check the input parameters.
400	IllegalParam.PreserveClientIpSwitch	The server group associated with the tcpssl listener does not support enabling PreserveClientIp.	The server group associated with the TCPSSL listener does not support client IP retention.
400	OperationDenied.RegionNotSupportHDMonitor	The operation is not allowed because of RegionNotSupportHDMonitor.	The current region does not support second-level monitoring.
403	Forbidden.NoPermission	Authentication is failed for NoPermission.	Authentication is failed for NoPermission.
404	ResourceNotFound.VSwitch	The specified resource of vSwitch is not found.	The specified vSwitch resource was not found. Please check the input parameters.
404	ResourceNotFound.loadBalancer	The specified resource of loadbalancer is not found.	The specified load balancer resource was not found. Please check the input parameters.
404	ResourceNotFound.serverGroup	The specified resource of serverGroup is not found.	The specified resource of serverGroup is not found. Please check the input parameters.
404	ResourceNotFound.CaCertificate	The specified resource of CaCertificate is not found.	Ca certificate does not exist, please check the input parameters.
404	ResourceNotFound.HdMonitorConfigNotExist	The specified resource of HdMonitorConfigNotExist is not found.	HdMonitorConfig does not exist, check the input parameters.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.