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.

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 listener name. 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 Network Load Balancer (NLB) instance ID.	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 valid values are 10 to 900. Default value: 900. If ListenerProtocol is set to UDP, the valid values are 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. 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 policies: Enter the ID of a custom security policy. To create a custom policy, refer to CreateSecurityPolicy. To query security policies, refer to ListSecurityPolicy. Note This parameter takes effect only for TCPSSL listeners.	tls_cipher_policy_1_0
CertificateIds	array	No	The server certificate list. This parameter takes effect only for TCPSSL listeners. Note Currently, you can add only one server certificate.
	string	No	The server certificate list. This parameter takes effect only for TCPSSL listeners. Note Currently, you can add only one server certificate.	123157******
CaCertificateIds	array	No	The CA certificate list. This parameter takes effect only for TCPSSL listeners. Note Currently, you can add only one CA certificate.
	string	No	The CA certificate list. This parameter takes effect only for TCPSSL listeners. Note Currently, 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: sends a precheck request without creating the listener. The system checks whether required parameters are specified, the request format, and service limits. 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 a regular request. If 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 generate a parameter value on your client to ensure that the value is unique across 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 query region IDs.	cn-hangzhou
ProxyProtocolEnabled	boolean	No	Specifies whether to use the Proxy Protocol to pass the client source IP address to backend servers. Valid values: true: enables the feature. false (default): disables the feature.	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 ALPN. Valid values: true: enables ALPN. false (default): disables ALPN.	false
AlpnPolicy	string	No	The ALPN policy. Valid values: HTTP1Only: negotiates only HTTP/1.x. The priority is HTTP/1.1 > HTTP/1.0. HTTP2Only: negotiates only HTTP/2. HTTP2Optional: prefers HTTP/1.x but also accepts HTTP/2. The priority is HTTP/1.1 > HTTP/1.0 > HTTP/2. HTTP2Preferred: prefers HTTP/2 but also accepts HTTP/1.x. The priority is HTTP/2 > HTTP/1.1 > HTTP/1.0. Note You must configure this parameter after AlpnEnabled is enabled.	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:`, or 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:`, or 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 backend servers by using the Proxy Protocol.
Ppv2CnIdEnabled	boolean	No	Ppv2CnIdEnabled
Ppv2PrivateLinkEpIdEnabled	boolean	No	Specifies whether to use the Proxy Protocol to pass the Ppv2PrivateLinkEpId to backend servers. Valid values: true: enables the feature. false (default): disables the feature.	false
Ppv2PrivateLinkEpsIdEnabled	boolean	No	Specifies whether to use the Proxy Protocol to pass the PrivateLinkEpsId to backend servers. Valid values: true: enables the feature. false (default): disables the feature.	false
Ppv2VpcIdEnabled	boolean	No	Specifies whether to use the Proxy Protocol to pass the VpcId to backend servers. Valid values: true: enables the feature. false (default): disables the feature.	false

Response elements

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

Examples

Success response

JSON format

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

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.