All Products
Search
Document Center

Server Load Balancer:SetLoadBalancerHTTPListenerAttribute

Last Updated:Mar 14, 2024

Modifies the configurations of an HTTP listener.

Operation description

Prerequisites

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:SetLoadBalancerHTTPListenerAttributeWRITE
  • acl
    acs:slb:{#regionId}:{#accountId}:acl/{#aclId}
  • loadbalancer
    acs:slb:{#regionId}:{#accountId}:loadbalancer/{#loadbalancerId}
  • slb:tag
none

Request parameters

ParameterTypeRequiredDescriptionExample
RegionIdstringNo

The region ID of the CLB instance.

You can query the region ID from the Regions and zones list or by calling the DescribeRegions operation.

cn-hangzhou
LoadBalancerIdstringYes

The CLB instance ID.

lb-bp1qjwo61pqz3ah*****
ListenerPortintegerYes

The frontend port that is used by the CLB instance.

Valid values: 1 to 65535.

80
BandwidthintegerNo

The maximum bandwidth of the listener. Unit: Mbit/s. Set the value to

  • -1: For a pay-by-data-transfer Internet-facing CLB instance, this value specifies that the bandwidth of the listener is unlimited.
-1
XForwardedForstringNo

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

  • on (default)
  • off
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
  • off
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 packet that is sent to a client. The next request from the client contains this cookie, and the listener distributes the request to the recorded backend server.

  • server: rewrites a cookie.

When CLB detects a user-defined cookie, CLB overwrites the original cookie with the user-defined cookie. The next request from the client carries the user-defined cookie, and the listener forwards the request to the recorded backend server.

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

The timeout period of a cookie.

Valid values: 1 to 86400. Unit: seconds.

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

The cookie that is configured on the server.

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

Note This parameter is required when StickySession is set to on and StickySessionType is set to server.
B490B5EBF6F3CD402E515D22BCDA****
HealthCheckstringNo

Specifies whether to enable the health check feature. Valid values:

  • on
  • off
on
HealthCheckMethodstringNo

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

Note The parameter takes effect only if you set HealthCheck 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 specify **$_ip or ignore HealthCheckDomain**, CLB uses the private IP addresses of backend servers as the health check domain names.
  • domain: The domain name must be 1 to 80 characters in length, and can contain letters, digits, periods (.), and hyphens (-).
Note The parameter takes effect only if you set HealthCheck to on.
172.XX.XX.16
HealthCheckURIstringNo

The Uniform Resource Identifier (URI) that you want to use for health checks.

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

Note The parameter takes effect only if you set HealthCheck to on.
/test/index.html
HealthyThresholdintegerNo

The number of times that an unhealthy backend server must consecutively pass health checks before it is declared healthy. In this case, the health status is changed from fail to success.

Valid values: 2 to 10.

Note The parameter takes effect only if you set HealthCheck to on.
4
UnhealthyThresholdintegerNo

The number of times that a healthy backend server must consecutively fail health checks before it is declared unhealthy. In this case, the health status is changed from success to fail.

Valid values: 2 to 10.

Note The parameter takes effect only if you set HealthCheck to on.
4
HealthCheckTimeoutintegerNo

The timeout period of a health check response. If a backend server, such as an Elastic Compute Service (ECS) instance, does not respond to a probe packet within the specified timeout period, the server fails the health check. This parameter takes effect only if you set HealthCheck to on.

Valid values: 1 to 300. Unit: seconds.

Note If the value of HealthCheckTimeout is smaller than the value of HealthCheckInterval, the value of HealthCheckTimeout becomes invalid and the value of HealthCheckInterval is used as the timeout period.
3
HealthCheckIntervalintegerNo

The interval at which health checks are performed.

Valid values: 1 to 50. Unit: seconds.

Note The parameter takes effect only if you set HealthCheck to on.
5
HealthCheckConnectPortintegerNo

The port that is used for health checks.

Valid values: 1 to 65535.

Note This parameter takes effect only if you set HealthCheck to on.
8080
HealthCheckHttpCodestringNo

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

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

Note The parameter takes effect only if you set HealthCheck to on.
http_2xx,http_3xx
VServerGroupstringNo

Specifies whether to use a vServer group. Valid values:

  • on
  • off
on
VServerGroupIdstringNo

The ID of the vServer group.

rsp-cige6j*****
XForwardedFor_SLBIPstringNo

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

  • on
  • off
on
XForwardedFor_SLBIDstringNo

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

  • on
  • off
on
XForwardedFor_protostringNo

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

  • on
  • off
on
GzipstringNo

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

  • on
  • off
on
AclIdstringNo

The ID of the access control list (ACL) that is associated with the listener.

Note This parameter is required when AclStatus is set to on.
123
AclTypestringNo

The type of the ACL. Valid values:

  • white: a whitelist. Only requests from the IP addresses or CIDR blocks in the ACL are forwarded. Whitelists apply to scenarios where you want to allow only specific IP addresses to access an application. Risks may occur if a whitelist is improperly configured. If a whitelist is configured, only requests from IP addresses that are added to the whitelist are forwarded by the listener.

If you enable a whitelist but do not add an IP address to the ACL, the listener forwards all requests.

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

If a blacklist is configured for a listener but no IP addresses are added to the blacklist, the listener forwards all requests.

Note This parameter takes effect when the value of AclStatus is set to on.
white
AclStatusstringNo

Specifies whether to enable access control. Valid values:

  • on
  • off
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 a request is received, CLB establishes a new connection.

12
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 within the request timeout period, CLB returns an HTTP 504 error code to the client.

3
DescriptionstringNo

The description of the listener.

test
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 request ID.

CEF72CEB-54B6-4AE8-B225-F876FF7BA984

Examples

Sample success responses

JSONformat

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

Error codes

HTTP status codeError codeError message
400IpVersionConflictThe ip version of this LoadBalancer and the Acl is conflict.
400Operation.NotAllowedOperation Denied. The HTTP listener does not support this action.
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.
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.
400InvalidParameter.ForwardCodeThe specified ForwardCode is invalid.

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
Input ParametersThe request parameters of the API has changed.
    Added Input Parameters: XForwardedFor_SLBPORT
    Added Input Parameters: XForwardedFor_ClientSrcPort