All Products
Search

This Product

    Server Load Balancer:UpdateListenerAttribute

    Document Center

    Server Load Balancer:UpdateListenerAttribute

    Last Updated:Dec 10, 2025

    Updates the attributes of a listener, such as the listener name and default actions.

    Operation description

    UpdateListenerAttribute is an asynchronous operation. After you send a request, the system returns a request ID and runs the task in the background. The listener configuration is not updated immediately. You can call the GetListenerAttribute operation to query the update status of the listener:

    • If a listener is in the Configuring state, it is being updated.

    • If a listener is in the Running state, it has been updated.

    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

    alb:UpdateListenerAttribute

    update

    *LoadBalancer

    acs:alb:{#regionId}:{#accountId}:loadbalancer/{#loadbalancerId}

    *SecurityPolicy

    acs:alb:{#regionId}:{#accountId}:securitypolicy/{#securitypolicyId}

    *ServerGroup

    acs:alb:{#regionId}:{#accountId}:servergroup/{#servergroupId}

    None

    None

    Request parameters

    Parameter

    Type

    Required

    Description

    Example

    ListenerId

    string

    Yes

    The ID of the Application Load Balancer (ALB) listener.

    lsn-123456

    ClientToken

    string

    No

    The client token that is used to ensure the idempotence of the request.

    The token must be unique among requests and can contain only ASCII characters.

    Note

    If you do not specify this parameter, the system uses the RequestId of the request as the ClientToken. The RequestId of each API request may be different.

    ettsdgfsdgdfg

    DryRun

    boolean

    No

    Specifies whether to perform a dry run. Valid values:

    • true: performs a dry run. The system checks the required parameters, request format, and service limits. If the request fails the dry run, an error message is returned. If the request passes the dry run, the system returns the DryRunOperation error code.

    • false (default): performs a normal request. If the request passes the check, the system returns a 2xx HTTP status code and performs the operation.

    true

    ListenerDescription

    string

    No

    The name of the listener.

    The name must be 2 to 256 characters in length and can contain letters, digits, Chinese characters, commas (,), periods (.), semicolons (;), forward slashes (/), at signs (@), underscores (_), and hyphens (-).

    test

    RequestTimeout

    integer

    No

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

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

    80

    IdleTimeout

    integer

    No

    The idle timeout period. Unit: seconds. Valid values: 1 to 60.

    If no request is received during the timeout period, ALB closes the current connection. When a new request is received, ALB establishes a new connection.

    15

    GzipEnabled

    boolean

    No

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

    • true

    • false

    false

    Http2Enabled

    boolean

    No

    Specifies whether to enable HTTP/2. Valid values:

    • true

    • false

    Note

    This parameter is available only for HTTPS listeners.

    false

    SecurityPolicyId

    string

    No

    The security policy. System security policies and custom security policies are supported.

    Note

    This parameter is available only for HTTPS listeners.

    tls_cipher_policy_1_0

    CaEnabled

    boolean

    No

    Specifies whether to enable mutual authentication. Valid values:

    • true

    • false

    true

    XForwardedForConfig

    object

    No

    The configuration of the `X-Forwarded-For` header.

    XForwardedForClientCertClientVerifyAlias

    string

    No

    The name of the custom header. This parameter takes effect only when XForwardedForClientCertClientVerifyEnabled is set to true.

    The name must be 1 to 40 characters in length and can contain letters, digits, underscores (_), and hyphens (-).

    Note

    This parameter is available only for HTTPS listeners.

    test_client-verify-alias_123456

    XForwardedForClientCertClientVerifyEnabled

    boolean

    No

    Specifies whether to use the X-Forwarded-Clientcert-Clientverify header to retrieve the verification result of the client certificate. Valid values:

    • true

    • false

    Note

    This parameter is available only for HTTPS listeners.

    false

    XForwardedForClientCertFingerprintAlias

    string

    No

    The name of the custom header. This parameter takes effect only when XForwardedForClientCertFingerprintEnabled is set to true.

    The name must be 1 to 40 characters in length and can contain letters, digits, underscores (_), and hyphens (-).

    Note

    This parameter is available only for HTTPS listeners.

    test_finger-print-alias_123456

    XForwardedForClientCertFingerprintEnabled

    boolean

    No

    Specifies whether to use the X-Forwarded-Clientcert-Fingerprint header to retrieve the fingerprint of the client certificate. Valid values:

    • true

    • false

    Note

    This parameter is available only for HTTPS listeners.

    false

    XForwardedForClientCertIssuerDNAlias

    string

    No

    The name of the custom header. This parameter takes effect only when XForwardedForClientCertIssuerDNEnabled is set to true.

    The name must be 1 to 40 characters in length and can contain letters, digits, underscores (_), and hyphens (-).

    Note

    This parameter is available only for HTTPS listeners.

    test_issue-dn-alias_123456

    XForwardedForClientCertIssuerDNEnabled

    boolean

    No

    Specifies whether to use the X-Forwarded-Clientcert-Issuerdn header to retrieve information about the issuer of the client certificate. Valid values:

    • true

    • false

    Note

    This parameter is available only for HTTPS listeners.

    false

    XForwardedForClientCertSubjectDNAlias

    string

    No

    The name of the custom header. This parameter takes effect only when XForwardedForClientCertSubjectDNEnabled is set to true.

    The name must be 1 to 40 characters in length and can contain letters, digits, underscores (_), and hyphens (-).

    Note

    This parameter is available only for HTTPS listeners.

    test_subject-dn-alias_123456

    XForwardedForClientCertSubjectDNEnabled

    boolean

    No

    Specifies whether to use the X-Forwarded-Clientcert-Subjectdn header to retrieve information about the owner of the client certificate. Valid values:

    • true

    • false

    Note

    This parameter is available only for HTTPS listeners.

    false

    XForwardedForClientSrcPortEnabled

    boolean

    No

    Specifies whether to use the X-Forwarded-Client-Srcport header to retrieve the client port. Valid values:

    • true

    • false

    Note

    This parameter is available for HTTP and HTTPS listeners.

    false

    XForwardedForEnabled

    boolean

    No

    Specifies whether to use the X-Forwarded-For header to retrieve the client's real IP address. Valid values:

    • true (default)

    • false

    Note

    1. If you set this parameter to true, the default value of XForwardedForProcessingMode is append. You can change the value to remove.

    2. If you set this parameter to false, the X-Forwarded-For header is preserved before the request is sent to the backend service. No extra processing is performed.

    3. This parameter is available for HTTP and HTTPS listeners.

    true

    XForwardedForProcessingMode

    string

    No

    The processing mode of the X-Forwarded-For header. This parameter takes effect only when XForwardedForEnabled is set to true. Valid values:

    • append (default): appends an IP address.

    • remove: deletes an IP address.

    Note

    1. If you set this parameter to append, the IP address of the last hop is added to the X-Forwarded-For header before the request is sent to the backend service.

    2. If you set this parameter to remove, the X-Forwarded-For header is deleted before the request is sent to the backend service, regardless of whether the request contains the X-Forwarded-For header.

    3. This parameter is available for HTTP and HTTPS listeners.

    append

    XForwardedForProtoEnabled

    boolean

    No

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

    • true

    • false

    Note

    This parameter is available for HTTP, HTTPS, and QUIC listeners.

    false

    XForwardedForSLBIdEnabled

    boolean

    No

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

    • true

    • false

    Note

    This parameter is available for HTTP, HTTPS, and QUIC listeners.

    false

    XForwardedForSLBPortEnabled

    boolean

    No

    Specifies whether to use the X-Forwarded-Port header to retrieve the listener port of the ALB instance. Valid values:

    • true

    • false

    Note

    This parameter is available for HTTP, HTTPS, and QUIC listeners.

    false

    XForwardedForClientSourceIpsEnabled

    boolean

    No

    Specifies whether to allow ALB to find the client's real IP address from the `X-Forwarded-For` header. Valid values:

    • true

    • false

    Note

    This parameter is available for HTTP and HTTPS listeners.

    false

    XForwardedForClientSourceIpsTrusted

    string

    No

    The trusted proxy IP address.

    ALB traverses the X-Forwarded-For header from the end to the beginning. ALB selects the first IP address that is not in the trusted IP address list as the client's real IP address. This IP address is used for throttling.

    10.1.1.0/24

    XForwardedForHostEnabled

    boolean

    No

    Specifies whether to use the X-Forwarded-Host header to retrieve the domain name that the client used to access the ALB instance. Valid values:

    • true

    • false (default)

    Note

    This parameter is available for HTTP, HTTPS, and QUIC listeners.

    false

    QuicConfig

    object

    No

    The QUIC listener association configuration.

    QuicListenerId

    string

    No

    The ID of the QUIC listener to associate. This parameter is required if QuicUpgradeEnabled is set to true. This parameter is available only for HTTPS listeners.

    Note

    The original listener and the associated QUIC listener must belong to the same ALB instance. The QUIC listener must not be associated with another listener.

    lsn-333

    QuicUpgradeEnabled

    boolean

    No

    Specifies whether to enable QUIC upgrade. Valid values:

    • true

    • false

    Note

    This parameter is available only for HTTPS listeners.

    false

    Certificates

    array<object>

    No

    The certificates.

    object

    No

    The certificate.

    CertificateId

    string

    No

    The ID of the default certificate. You can add only one default server certificate.

    Note

    123157******

    CaCertificates

    array<object>

    No

    The CA certificates. You can specify only one CA certificate.

    object

    No

    The CA certificate.

    CertificateId

    string

    No

    The ID of the CA certificate.

    Note

    This parameter is required if CaEnabled is set to true.

    123359******

    DefaultActions

    array<object>

    No

    The default actions for the forwarding rule.

    array<object>

    No

    The default action.

    ForwardGroupConfig

    object

    No

    The configuration of the forwarding action. This parameter is required and takes effect if Type is set to ForwardGroup. You can specify a maximum of 20 forwarding actions.

    ServerGroupTuples

    array<object>

    Yes

    The server group to which requests are forwarded.

    object

    No

    The server group.

    ServerGroupId

    string

    Yes

    The ID of the server group to which requests are forwarded.

    sgp-i5qt20******

    Type

    string

    Yes

    The action type. You can specify only one action type.

    Set the value to ForwardGroup. This forwards requests to multiple server groups.

    ForwardGroup

    Response elements

    Element

    Type

    Description

    Example

    object

    The response.

    JobId

    string

    The ID of the asynchronous task.

    72dcd26b-f12d-4c27-b3af-18f6aed5****

    RequestId

    string

    The request ID.

    365F4154-92F6-4AE4-92F8-7FF******

    Examples

    Success response

    JSON format

    {
  "JobId": "72dcd26b-f12d-4c27-b3af-18f6aed5****",
  "RequestId": "365F4154-92F6-4AE4-92F8-7FF******"
}

    Error codes

    HTTP status code

    Error code

    Error message

    Description

    400

    IncorrectStatus.LoadBalancer

    The status of %s [%s] is incorrect.

    400

    IncorrectBusinessStatus.LoadBalancer

    The business status of %s [%s]  is incorrect.

    The business status of %s [%s]  is incorrect.

    400

    IncorrectStatus.Listener

    The status of %s [%s] is incorrect.

    400

    OperationDenied.CrossLoadBalancerQUICListener

    The operation is not allowed because of %s.

    The operation is not allowed because of %s.

    400

    ResourceAlreadyAssociated.Listener

    The specified resource %s is already associated.

    The specified resource %s is already associated.

    400

    OperationDenied.GRPCServerGroup

    The operation is not allowed because of %s.

    400

    ResourceAlreadyAssociated.Certificate

    The specified resource %s is already associated.

    400

    ResourceQuotaExceeded.SecurityPolicyAttachedNum

    The quota of %s is exceeded for resource %s, usage %s/%s.

    The quota of %s is exceeded for resource %s. Usage: %s/%s.

    400

    ResourceQuotaExceeded.ServerGroupAttachedNum

    The quota of %s is exceeded for resource %s, usage %s/%s.

    400

    ResourceQuotaExceeded.LoadBalancerServersNum

    The quota of %s is exceeded for resource %s, usage %s/%s.

    400

    ResourceQuotaExceeded.ServerAddedNum

    The quota of %s is exceeded for resource %s, usage %s/%s.

    400

    OperationDenied.ServerGroupProtocolNotSupport

    The operation is not allowed because of ServerGroupProtocolNotSupport.

    The operation is not allowed because the server group protocol is not supported.

    400

    UnsupportedFeature.FullTraceHttps

    The feature of FullTraceHttps is not supported for current instance.

    400

    ResourceInConfiguring.Listener

    The specified resource of %s is being configured, please try again later.

    The specified resource of %s is being configured, please try again later.

    400

    Mismatch.VpcId

    The %s is mismatched for %s and %s.

    The %s is mismatched for %s and %s.

    400

    InvalidParameter

    Invalid parameter, please check the parameter input.

    Invalid parameter, please check the parameter input.

    403

    Forbidden.LoadBalancer

    Authentication is failed for %s.

    Authentication is failed for %s.

    404

    ResourceNotFound.Listener

    The specified resource %s is not found.

    404

    ResourceNotFound.ServerGroup

    The specified resource %s is not found.

    404

    ResourceNotFound.SecurityPolicy

    The specified resource %s is not found.

    The specified resource %s is not found.

    404

    ResourceNotFound.Certificate

    The specified resource %s is not found.

    The specified resource %s is not found.

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.