All Products
Search
Document Center

Server Load Balancer:SetLoadBalancerHTTPSListenerAttribute

Last Updated:Mar 14, 2024

Modifies the configurations of an HTTPS listener.

Operation description

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer.

Authorization information

The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

  • Operation: the value that you can use in the Action element to specify the operation on a resource.
  • Access level: the access level of each operation. The levels are read, write, and list.
  • Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
    • The required resource types are displayed in bold characters.
    • If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
  • Condition Key: the condition key that is defined by the cloud service.
  • Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.
OperationAccess levelResource typeCondition keyAssociated operation
slb:SetLoadBalancerHTTPSListenerAttributeWRITE
  • acl
    acs:slb:{#regionId}:{#accountId}:acl/{#aclId}
  • certificate
    acs:slb:{#regionId}:{#accountId}:certificate/{#certificateId}
  • loadbalancer
    acs:slb:{#regionId}:{#accountId}:loadbalancer/{#loadbalancerId}
  • slb:tag
none

Request parameters

ParameterTypeRequiredDescriptionExample
RegionIdstringNo

The ID of the region where the CLB instance is deployed.

You can call the DescribeRegions operation to query the most recent region list.

cn-hangzhou
LoadBalancerIdstringYes

The ID of the CLB instance.

lb-sjhfdji****
ListenerPortintegerYes

The frontend port that is used by the CLB instance.

Valid values: 1 to 65535.

80
BandwidthintegerNo

The bandwidth limit of the listener. Unit: Mbit/s.

Valid values: -1 and 1 to 5120.

  • -1: If you set the value to -1, the bandwidth of the listener is unlimited.
  • 1 to 5120: If you set a value from 1 to 5120, the value that you specify equals the bandwidth limit of the listener. The sum of bandwidth limit values that you specify for all listeners of the CLB instance cannot exceed the bandwidth limit of the CLB instance.
-1
XForwardedForstringNo

Specifies whether to use the X-Forwarded-For header to retrieve client IP addresses. Valid values:

  • on: yes
  • off: no
on
SchedulerstringNo

The scheduling algorithm. Valid values:

  • wrr: Backend servers that have higher weights receive more requests than backend servers that have lower weights.
  • rr: Requests are distributed to backend servers in sequence.
wrr
StickySessionstringNo

Specifies whether to enable session persistence. Valid values:

  • on: yes
  • off: no
on
StickySessionTypestringNo

The method that is used to handle a cookie. Valid values:

  • insert: inserts a cookie.

    CLB inserts a cookie (SERVERID) into the first HTTP or HTTPS response that is sent to a client. The next request from the client will contain this cookie, and the listener will distribute this request to the recorded backend server.

  • server: rewrites a cookie.

    When CLB detects a user-defined cookie, it overwrites the original cookie with the user-defined cookie. The next request from the client will contain the user-defined cookie, and the listener will distribute this request to the recorded backend server.

Note This parameter is required if the StickySession parameter is set to on.
insert
CookieTimeoutintegerNo

The timeout period of the cookie. Unit: seconds.

Valid values: 1 to 86400.

Note This parameter is required if the StickySession parameter is set to on and the StickySessionType parameter is set to insert.
500
CookiestringNo

The cookie to be configured on the backend server.

The cookie must be 1 to 200 characters in length, and can contain only ASCII characters and digits. It cannot contain commas (,), semicolons (;), or space characters. It cannot start with a dollar sign ($).

Note This parameter is required if the StickySession parameter is set to on and the StickySessionType parameter is set to server.
B490B5EBF6F3CD4****
HealthCheckstringNo

Specifies whether to enable health checks. Valid values:

  • on: yes
  • off: no
on
HealthCheckMethodstringNo

The HTTP method that is used for health checks. Valid values: head and get.

Note This parameter takes effect only when the HealthCheck parameter is set to on.
get
HealthCheckDomainstringNo

The domain name that is 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, the CLB instance 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 (-).
Note This parameter takes effect only when the HealthCheck parameter is set to on.
172.XX.XX.16
HealthCheckURIstringNo

The URL that is used for health checks.

The URL must be 1 to 80 characters in length and can contain letters, digits, and the following characters: - / . % ? # &. The URL must not be a single forward slash (/) but it must start with a forward slash (/).

Note This parameter takes effect only when the HealthCheck parameter is set to on.
/test/index.html
HealthyThresholdintegerNo

The number of health checks that an unhealthy backend server must consecutively pass before it can be declared healthy (from fail to success).

Valid values: 2 to 10.

Note This parameter takes effect only when the HealthCheck parameter is set to on.
4
UnhealthyThresholdintegerNo

The number of health checks that a healthy backend server must consecutively fail before it can be declared unhealthy (from success to fail).

Valid values: 2 to 10.

Note This parameter takes effect only when the HealthCheck parameter is set to on.
4
HealthCheckTimeoutintegerNo

The timeout period of a health check response. If a backend server does not respond within the specified timeout period, the health check fails. Unit: seconds.

Valid values: 1 to 300.

If the value of the HealthCheckTimeout parameter is smaller than that of the HealthCheckInterval parameter, the timeout period specified by the HealthCheckTimeout parameter is ignored and the period of time specified by the HealthCheckInterval parameter is used as the timeout period.

Note This parameter takes effect only when the HealthCheck parameter is set to on.
3
HealthCheckIntervalintegerNo

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

Valid values: 1 to 50.

Note This parameter takes effect only when the HealthCheck parameter is set to on.
5
HealthCheckConnectPortintegerNo

The port that is used for health checks.

Valid values: 1 to 65535.

Note This parameter takes effect only when the HealthCheck parameter is set to on.
8080
HealthCheckHttpCodestringNo

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

Valid values: http_2xx, http_3xx, http_4xx, and http_5xx.

Note This parameter takes effect only when the HealthCheck parameter is set to on.
http_2xx,http_3xx
ServerCertificateIdstringNo

The ID of the server certificate.

idkp-123-cn-te****
CACertificateIdstringNo

The ID of the CA certificate.

  • If both the CA certificate and the server certificate are uploaded, mutual authentication is used.
  • If you upload only the server certificate, one-way authentication is used.
139a00604ad-cn-east-****
VServerGroupstringNo

Specifies whether to use a vServer group. Valid values:

  • on: yes
  • off: no
on
VServerGroupIdstringNo

The ID of the vServer group.

rsp-cige6j****
XForwardedFor_SLBIPstringNo

Specifies whether to use the SLB-IP header to obtain the virtual IP address (VIP) requested by the client. Valid values:

  • on: yes
  • off: no
on
XForwardedFor_SLBIDstringNo

Specifies whether to use the SLB-ID header to retrieve the ID of the CLB instance. Valid values:

  • on: yes
  • off: no
on
XForwardedFor_protostringNo

Specifies whether to use the X-Forwarded-Proto header to retrieve the listener protocol. Valid values:

  • on: yes
  • off: no
on
GzipstringNo

Specifies whether to enable Gzip compression to compress specific types of files. Valid values:

  • on: yes
  • off: no
on
AclIdstringNo

The ID of the network access control list (ACL) that you want to associate with the listener.

If AclStatus is set to on, this parameter is required.

nacl-a2do9e413e0spzasx****
AclTypestringNo

The type of network ACL. Valid values:

  • white: a whitelist. Only requests from the IP addresses or CIDR blocks in the network 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 no IP address is added to the whitelist, the CLB listener forwards all requests.

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

    If no IP address is added to the blacklist, the listener forwards all requests.

Note This parameter takes effect only when AclStatus is set to on.
white
AclStatusstringNo

Specifies whether to enable access control. Valid values:

  • on: enables access control
  • off: disables access control
off
IdleTimeoutintegerNo

The timeout period of an idle connection. Unit: seconds. Valid values: 1 to 60. Default value: 15.

If no request is received within the specified timeout period, CLB closes the connection. When another request is received, CLB establishes a new connection.

23
RequestTimeoutintegerNo

The timeout period of a request. Unit: seconds. Valid values: 1 to 180. Default value: 60.

If no response is received from the backend server during the request timeout period, CLB sends an HTTP 504 error code to the client.

223
EnableHttp2stringNo

Specifies whether to use HTTP 2.0. Valid values:

  • on: yes
  • off: no
off
TLSCipherPolicystringNo

The Transport Layer Security (TLS) security policy. Each security policy contains TLS protocol versions and cipher suites available for HTTPS.

  • tls_cipher_policy_1_0:

    Supported TLS versions: TLS 1.0, TLS 1.1, and TLS 1.2

    Supported cipher suites: ECDHE-RSA-AES128-GCM-SHA256, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-RSA-AES128-SHA256, ECDHE-RSA-AES256-SHA384, AES128-GCM-SHA256, AES256-GCM-SHA384, AES128-SHA256, AES256-SHA256, ECDHE-RSA-AES128-SHA, ECDHE-RSA-AES256-SHA, AES128-SHA, AES256-SHA, and DES-CBC3-SHA

  • tls_cipher_policy_1_1:

    Supported TLS versions: TLS 1.1 and TLS 1.2

    Supported cipher suites: ECDHE-RSA-AES128-GCM-SHA256, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-RSA-AES128-SHA256, ECDHE-RSA-AES256-SHA384, AES128-GCM-SHA256, AES256-GCM-SHA384, AES128-SHA256, AES256-SHA256, ECDHE-RSA-AES128-SHA, ECDHE-RSA-AES256-SHA, AES128-SHA, AES256-SHA, and DES-CBC3-SHA

  • tls_cipher_policy_1_2

    Supported TLS version: TLS 1.2

    Supported cipher suites: ECDHE-RSA-AES128-GCM-SHA256, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-RSA-AES128-SHA256, ECDHE-RSA-AES256-SHA384, AES128-GCM-SHA256, AES256-GCM-SHA384, AES128-SHA256, AES256-SHA256, ECDHE-RSA-AES128-SHA, ECDHE-RSA-AES256-SHA, AES128-SHA, AES256-SHA, and DES-CBC3-SHA

  • tls_cipher_policy_1_2_strict

    Supported TLS version: TLS 1.2

    Supported cipher suites: ECDHE-RSA-AES128-GCM-SHA256, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-RSA-AES128-SHA256, ECDHE-RSA-AES256-SHA384, ECDHE-RSA-AES128-SHA, and ECDHE-RSA-AES256-SHA

  • tls_cipher_policy_1_2_strict_with_1_3

    Supported TLS versions: TLS 1.2 and TLS 1.3

    Supported cipher suites: TLS_AES_128_GCM_SHA256, TLS_AES_256_GCM_SHA384, TLS_CHACHA20_POLY1305_SHA256, TLS_AES_128_CCM_SHA256, TLS_AES_128_CCM_8_SHA256, ECDHE-ECDSA-AES128-GCM-SHA256, ECDHE-ECDSA-AES256-GCM-SHA384, ECDHE-ECDSA-AES128-SHA256, ECDHE-ECDSA-AES256-SHA384, ECDHE-RSA-AES128-GCM-SHA256, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-RSA-AES128-SHA256, ECDHE-RSA-AES256-SHA384, ECDHE-ECDSA-AES128-SHA, ECDHE-ECDSA-AES256-SHA, ECDHE-RSA-AES128-SHA, and ECDHE-RSA-AES256-SHA

tls_cipher_policy_1_2
DescriptionstringNo

The description of the listener.

Listener1
XForwardedFor_SLBPORTstringNo

Specifies whether to use the XForwardedFor_SLBPORT header to retrieve the listener port of the CLB instance. Valid values:

  • on
  • off
off
XForwardedFor_ClientSrcPortstringNo

Specifies whether to use the XForwardedFor_ClientSrcPort header to retrieve the client port. Valid values:

  • on
  • off
off

Response parameters

ParameterTypeDescriptionExample
object
RequestIdstring

The ID of the request.

CEF72CEB-54B6-4AE8-B225-F876FF7BA984

Examples

Sample success responses

JSONformat

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

Error codes

HTTP status codeError codeError message
400ParamDuplicateErrorThe specified parameter value of XForwardedFor_ClientCertSubjectDNAlias is duplicate. Please change to a different one.
400ParamDuplicateErrorThe specified parameter value of XForwardedFor_ClientCertIssuerDNAlias is duplicate. Please change to a different one.
400ParamDuplicateErrorThe specified parameter value of XForwardedFor_ClientCertFingerprintAlias is duplicate. Please change to a different one.
400ParamDuplicateErrorThe specified parameter value of XForwardedFor_ClientCertClientVerifyAlias is duplicate. Please change to a different one.
400IpVersionConflictThe ip version of this LoadBalancer and the Acl is conflict.
400InvalidParameter.IdleTimeoutThe specified IdleTimeout exceeds the limit.
400InvalidParameter.RequestTimeoutThe specified RequestTimeout exceeds the limit.
400ListenerForwardNotSupportX-Forward-For is not supported to a ipv6 instance.
400InvalidParameter.RegionNotSupportThe region does not support the parameter: %s.
400InvalidParameter.SpecNotSupportThe loadBalancer of shared spec does not support the parameter: %s.
400OperationFailed.ServerGroupInUseThe VServerGroup or MasterSlaveServerGroup can not be close for this listener.
400InvalidParameter.VServerGroupIdThe MasterSlaveServerGroup can not be attached to HTTP or HTTPS listener.
400MissingParam.HealthCheckDomainThe HealthCheckDomain is required when HealthCheckHttpVersion is http1.1.
400InvalidParameter.HealthCheckHttpVersionThe param HealthCheckHttpVersion is invalid.
400QuotaLimitExceeds.AclAttachedToListener%s.
400QuotaLimitExceeds.TotalAclEntry%s.
400AclListenerOverLimit%s.
400Duplicated.AclEntry%s.
400CertificateNotExistThe specified CertificateId does not exist.
400InvalidTLSPolicyId.NotExistThe specified TLS cipher policy does not exist.
400TLSPolicyConfiguringThe specified TLS cipher policy is configuring.
400TLSCipherPolicyVipRelationOverLimitThe number of listeners associated with a policy has exceeded.
400TooManyCertificatesThe number of certificates must not be greater than one.
400CertificateTypeMismatchedThe certificate type does not match.
400MissingParam.ServerCertificatesServer certificates are required.
400CnCertificateNotSupportThe cn certificate is not support.
400InvalidParam.CertificateBindingTypeThe param CertificateBindingType is invalid.
400InvalidParamSize.ServerCertificatesThe size of param ServerCertificates is invalid.
400TooManyCertificates.ServerCertificatesThe number of certificates must not be greater than one.
404ResourceNotFound.CertificateThe specified resource is not found.

For a list of error codes, visit the Service error codes.

Change history

Change timeSummary of changesOperation
2023-12-14The Error code has changed. The request parameters of the API has changedsee changesets
Change itemChange content
Error CodesThe Error code has changed.
    delete Error Codes: 400
    delete Error Codes: 404
Input ParametersThe request parameters of the API has changed.
    Added Input Parameters: XForwardedFor_SLBPORT
    Added Input Parameters: XForwardedFor_ClientSrcPort