All Products
Search

This Product

    Server Load Balancer:SetLoadBalancerHTTPSListenerAttribute

    Document Center

    Server Load Balancer:SetLoadBalancerHTTPSListenerAttribute

    Last Updated:Sep 08, 2026

    Modifies the configurations of an HTTPS 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:SetLoadBalancerHTTPSListenerAttribute

    update

    acl

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

    *certificate

    acs:slb:{#regionId}:{#accountId}:certificate/{#certificateId}

    *loadbalancer

    acs:slb:{#regionId}:{#accountId}:loadbalancer/{#loadbalancerId}
    • slb:tag
    • 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 call the DescribeRegions operation to query region IDs.

    cn-hangzhou
    LoadBalancerId

    string

    Yes

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

    lb-sjhfdji****
    ListenerPort

    integer

    Yes

    The frontend port used by the Classic Load Balancer (CLB) instance.

    Valid values: 1 to 65535.

    80
    Bandwidth

    integer

    No

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

    Valid values:

    • -1: The peak bandwidth is not limited.

    -1
    XForwardedFor

    string

    No

    Specifies whether to use the X-Forwarded-For header field to obtain the real IP address of the client. Valid values:

    • on: yes.

    • off: no.

    on
    Scheduler

    string

    No

    The scheduling algorithm. Valid values:

    • wrr: Backend servers with higher weights receive more requests than backend servers with lower weights.

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

    wrr
    StickySession

    string

    No

    Specifies whether to enable session persistence. Valid values:

    • on: yes.

    • off: no.

    on
    StickySessionType

    string

    No

    The method used to handle the cookie. Valid values:

    • insert: insert cookie.

    When a client accesses Server Load Balancer for the first time, Server Load Balancer inserts a cookie into the response (inserts SERVERID into the HTTP/HTTPS response). The next time the client sends a request with this cookie, Server Load Balancer forwards the request to the backend server that was previously recorded.

    • server: rewrite cookie.

    When Server Load Balancer discovers that a user has defined a custom cookie, it rewrites the original cookie. The next time the client sends a request with the new cookie, Server Load Balancer forwards the request to the backend server that was previously recorded.

    Note

    This parameter is required when StickySession is set to on.

    insert
    CookieTimeout

    integer

    No

    The timeout period of the cookie.

    Valid values: 1 to 86400 (seconds).

    Note

    This parameter is required when StickySession is set to on and StickySessionType is set to insert.

    500
    Cookie

    string

    No

    The cookie configured on the server.

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

    Note

    This parameter is required when StickySession is set to on and StickySessionType is set to server.

    testCookie
    HealthCheck

    string

    No

    Specifies whether to enable health checks. Valid values:

    • on: yes.

    • off: no.

    on
    HealthCheckMethod

    string

    No

    The health check method used by the HTTP health check. Valid values: head and get.

    Note

    This parameter takes effect only when HealthCheck is set to on.

    get
    HealthCheckDomain

    string

    No

    The domain name used for health checks. Valid values:

    • $_ip: the private IP address of the backend server. If you specify $_ip or do not specify this parameter, Server Load Balancer 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 only letters, digits, periods (.), and hyphens (-).

    Note

    This parameter takes effect only when HealthCheck is set to on.

    172.XX.XX.16
    HealthCheckURI

    string

    No

    The URI used for health checks.

    The value must be 1 to 80 characters in length and can contain letters, digits, hyphens (-), forward slashes (/), periods (.), percent signs (%), question marks (?), number signs (#), and ampersands (&). The URI cannot contain only a forward slash (/) but must start with a forward slash (/).

    Note

    This parameter takes effect only when HealthCheck is set to on.

    /test/index.html
    HealthyThreshold

    integer

    No

    The number of consecutive successful health checks that must occur before a backend server is declared healthy (from fail to success).

    Valid values: 2 to 10.

    Note

    This parameter takes effect only when HealthCheck is set to on.

    4
    UnhealthyThreshold

    integer

    No

    The number of consecutive failed health checks that must occur before a backend server is declared unhealthy (from success to fail).

    Valid values: 2 to 10.

    Note

    This parameter takes effect only when HealthCheck is set to on.

    4
    HealthCheckTimeout

    integer

    No

    The amount of time to wait for a response from a health check. If the backend ECS instance does not respond within the specified time, the health check fails. Unit: seconds. Valid values: 1 to 300.

    Note

    This parameter takes effect only when HealthCheck is set to on.

    3
    HealthCheckInterval

    integer

    No

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

    Valid values: 1 to 50.

    Note

    This parameter takes effect only when HealthCheck is set to on.

    5
    HealthCheckConnectPort

    integer

    No

    The port used for health checks.

    Valid values: 1 to 65535.

    Note

    This parameter takes effect only when HealthCheck is set to on.

    8080
    HealthCheckHttpCode

    string

    No

    The HTTP status code that indicates 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 HealthCheck is set to on.

    http_2xx,http_3xx
    ServerCertificateId

    string

    No

    The ID of the server certificate.

    idkp-123-cn-te****
    CACertificateId

    string

    No

    The ID of the CA certificate.

    • If you upload both a CA certificate and a server certificate, mutual authentication is used.

    • If you upload only a server certificate, one-way authentication is used.

    139a00604ad-cn-east-****
    VServerGroup

    string

    No

    Specifies whether to use a vServer group. Valid values:

    • on: yes.

    • off: no.

    on
    VServerGroupId

    string

    No

    The ID of the vServer group.

    rsp-cige6j****
    XForwardedFor_SLBIP

    string

    No

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

    • on: yes.

    • off: no.

    on
    XForwardedFor_SLBID

    string

    No

    Specifies whether to use the SLB-ID header field to obtain the SLB instance ID. Valid values:

    • on: yes.

    • off: no.

    on
    XForwardedFor_proto

    string

    No

    Specifies whether to use the X-Forwarded-Proto header field to obtain the listener protocol of the SLB instance. Valid values:

    • on: yes.

    • off: no.

    on
    Gzip

    string

    No

    Specifies whether to enable Gzip compression for specific file types. Valid values:

    • on: yes.

    • off: no.

    on
    AclId

    string

    No

    The ID of the access control list (ACL) bound to the listener.

    This parameter is required when AclStatus is set to on.

    acl-a2do9e413e0spzasx****
    AclType

    string

    No

    The type of access control. Valid values:

    • white: Only requests from the IP addresses or CIDR blocks in the selected access control policy group are forwarded. Whitelists apply to scenarios in which you want to allow only specific IP addresses to access your service. Enabling a whitelist poses some risks. After a whitelist is enabled, only the IP addresses in the whitelist can access the SLB listener.

    If a whitelist is enabled but no IP address is added to the access control policy group, the SLB listener forwards all requests.

    • black: All requests from the IP addresses or CIDR blocks in the selected access control policy group are rejected. Blacklists apply to scenarios in which you want to block access from specific IP addresses.

    If a blacklist is enabled but no IP address is added to the access control policy group, the SLB listener forwards all requests.

    Note

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

    white
    AclStatus

    string

    No

    Specifies whether to enable access control. Valid values:

    • on: yes.

    • off: no.

    off
    IdleTimeout

    integer

    No

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

    If no access request is received during the specified timeout period, Server Load Balancer temporarily breaks the current connection and re-establishes a new connection when the next request arrives.

    23
    RequestTimeout

    integer

    No

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

    If no response is received from the backend server during the specified timeout period, Server Load Balancer stops waiting and returns an HTTP 504 error code to the client.

    223
    EnableHttp2

    string

    No

    Specifies whether to enable the HTTP 2.0 feature. Valid values:

    • on: yes.

    • off: no.

    off
    TLSCipherPolicy

    string

    No

    The security policy that contains the TLS protocol versions and supported encryption algorithm suites available for HTTPS.

    • tls_cipher_policy_1_0:

      Supported TLS versions: TLSv1.0, TLSv1.1, and TLSv1.2.

      Supported encryption algorithm 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: TLSv1.1 and TLSv1.2.

      Supported encryption algorithm 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 versions: TLSv1.2.

      Supported encryption algorithm 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 versions: TLSv1.2.

      Supported encryption algorithm 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: TLSv1.2 and TLSv1.3.

      Supported encryption algorithm 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
    Description

    string

    No

    The custom listener name.

    The name must be 1 to 256 characters in length and can contain Chinese characters, letters, digits, hyphens (-), forward slashes (/), periods (.), and underscores (_).

    https_80
    XForwardedFor_SLBPORT

    string

    No

    Specifies whether to use the XForwardedFor_SLBPORT header field to obtain the listener port of the SLB instance. Valid values:

    • on: yes.

    • off: no.

    off
    XForwardedFor_ClientSrcPort

    string

    No

    Specifies whether to use the XForwardedFor_ClientSrcPort header field to obtain the port of the client that accesses the SLB instance. Valid values:

    • on: yes.

    • off: no.

    off
    DryRun

    boolean

    No

    Response elements

    Element

    Type

    Description

    Example

    object

    RequestId

    string

    The request ID.

    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 ParamDuplicateError The specified parameter value of XForwardedFor_ClientCertSubjectDNAlias is duplicate. Please change to a different one. The XForwardedFor_ClientCertClientVerifyAlias parameter is duplicated.
    400 IpVersionConflict The ip version of this LoadBalancer and the Acl is conflict. The IP version of the specified Server Load Balancer instance conflicts with the IP type supported by the ACL.
    400 InvalidParameter.IdleTimeout The specified IdleTimeout exceeds the limit. The specified IdleTimeout is invalid. Check the parameter constraints and try again after making corrections.
    400 InvalidParameter.RequestTimeout The specified RequestTimeout exceeds the limit. The specified RequestTimeout is invalid. Check the parameter constraints and try again.
    400 ListenerForwardNotSupport X-Forward-For is not supported to a ipv6 instance. IPv6 SLB instances do not support X-Forwarded-For.
    400 InvalidParameter.RegionNotSupport The region does not support the parameter: %s. The specified parameter is not supported in the current region.
    400 InvalidParameter.SpecNotSupport The loadBalancer of shared spec does not support the parameter: %s. The specified parameter is not supported by shared-resource SLB instances.
    400 OperationFailed.ServerGroupInUse The VServerGroup or MasterSlaveServerGroup can not be close for this listener. The operation failed because the current listener does not support disabling the server group.
    400 InvalidParameter.VServerGroupId The MasterSlaveServerGroup can not be attached to HTTP or HTTPS listener. HTTP or HTTPS listeners do not support primary/secondary server groups.
    400 MissingParam.HealthCheckDomain The HealthCheckDomain is required when HealthCheckHttpVersion is http1.1. The HealthCheckDomain parameter is missing.
    400 InvalidParameter.HealthCheckHttpVersion The param HealthCheckHttpVersion is invalid. The specified HealthCheckHttpVersion is invalid. Check the parameter constraints and try again after making corrections.
    400 Duplicated.AclEntry %s. %s
    400 CertificateNotExist The specified CertificateId does not exist. The specified certificate does not exist.
    400 InvalidTLSPolicyId.NotExist The specified TLS cipher policy does not exist. The specified TLS security policy does not exist.
    400 TLSPolicyConfiguring The specified TLS cipher policy is configuring. The specified TLSCipherPolicy is being modified.
    400 TLSCipherPolicyVipRelationOverLimit The number of listeners associated with a policy has exceeded. The number of TLSCipherPolicy instances associated with the listener has reached the quota limit.
    400 TooManyCertificates The number of certificates must not be greater than one. The number of certificates cannot exceed 1.
    400 CertificateTypeMismatched The certificate type does not match. The type of the specified certificate does not match.
    400 MissingParam.ServerCertificates Server certificates are required. The ServerCertificates parameter is missing.
    400 CnCertificateNotSupport The cn certificate is not support. China National Cryptographic Algorithm (SM) certificates are not supported.
    400 InvalidParam.CertificateBindingType The param CertificateBindingType is invalid. The specified CertificateBindingType is invalid. Check the parameter constraints and try again after you make modifications.
    400 InvalidParamSize.ServerCertificates The size of param ServerCertificates is invalid. The length of the specified ServerCertificates is invalid. Check the parameter constraints and try again.
    400 TooManyCertificates.ServerCertificates The number of certificates must not be greater than one. The number of certificates cannot exceed 1.
    400 AclListenerOverLimit This acl has reached the limit of binding to listeners. The number of listeners that can be associated with the specified ACL has reached the quota limit.
    400 QuotaLimitExceeds.AclAttachedToListener The number of Acl bound listeners has reached the quota limit The number of listeners associated with the ACL has reached the quota limit.
    400 QuotaLimitExceeds.TotalAclEntry The number of Acl entries has reached the quota limit. The number of ACL entries has reached the quota limit.
    400 QuotaLimitExceeds.AclListenerOverLimit This acl has reached the limit of binding to listeners. The number of listeners that can be associated with the specified ACL has reached the quota limit.
    400 DryRunOperation Request validation has been passed with DryRun flag set. Request validation has been passed with DryRun flag set.
    404 ResourceNotFound.Certificate The specified resource is not found.

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.