> For the complete documentation index, see [llms.txt](https://docs.console.zenlayer.com/api-reference/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.console.zenlayer.com/api-reference/zlb/load-balancer-listener/modifylistener.md).
# ModifyListener
## 1. API Description
This API (ModifyListener) is used to modify the properties of a load balance listener, including its name, health check parameters, and forwarding rules. The listening protocol cannot be modified.
{% hint style="info" %}
**Notes**
* Modifying the listening protocol of a listener is not supported.
* `algoOpts` (stateless forwarding) and `persistent` (session persistence) are mutually exclusive because stateless forwarding hashes packets individually and does not maintain a connection-tracking table, so it cannot guarantee that the same client always hits the same backend.
* A disabled `algoOpts` is not represented as `None` on the query side: query interfaces such as [DescribeListeners](/api-reference/zlb/load-balancer-listener/describelisteners.md) never return `None`; when the option is not enabled, the field is always empty.
{% endhint %}
## 2. Input Parameters
The following request parameter list only provides API request parameters.
| Parameter Name | Required | Type | Description |
| -------------- | -------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| loadBalancerId | Yes | String | Load balancer ID.
It can be obtained by calling DescribeLoadBalancers.
|
| listenerId | Yes | String | Listener ID of the load balancer.
It can be obtained by calling DescribeListeners.
|
| listenerName | No | String | The name of the listener for the load balancer.
It will not be modified if not passed in.
|
| healthCheck | No | [HealthCheck](/api-reference/zlb/datastructure.md#healthcheck) | Health check of the load balancer listener.
If not passed, it is not modified. To enable or disable health check, set the HealthCheck.enabled field.
|
| scheduler | No | [ListenerScheduler](/api-reference/zlb/datastructure.md#listenerscheduler) | Scheduling algorithm of the listener.
It will not be modified if not passed in.
|
| port | No | String | Listening port.
Multiple ports are separated by commas (,).
A port range is connected with -, for example: 10000-10005.
Valid port values range from 0 to 65535, where 0 indicates all ports.
If not specified, it is not modified.
Both a port range and all ports are counted as 1 port in quota calculation.
Consecutive individual ports are automatically merged into a port range before being saved and returned. For example, 1,2,3,4,5 is saved as 1-5.
|
| kind | No | [LoadBalancerKind](/api-reference/zlb/datastructure.md#loadbalancerkind) | Forwarding mode.
After it is changed to DR mode, the ports specified on the backend servers become invalid and always follow the listener ports.
After modification, it must be consistent with the forwarding mode of the other listeners under the load balancer.
In DR mode, the listener cannot be set to all ports (0); if the current port of the listener is already all ports (0), it cannot be changed to DR either.
When the ipStackType of the load balancer instance is IPv6, only DR is supported.
|
| persistent | No | Integer | Session persistence duration, in seconds.
Mutually exclusive with algoOpts (advanced scheduling-algorithm option): if this listener already has algoOpts enabled, it cannot be modified to a non-zero value unless algoOpts=None is passed in the same request to clear it.
Value range: \[0, +)
|
| idleTimeout | No | Integer | Idle timeout period. Unit: seconds.
Value range: \[60, +)
|
| algoOpts | No | [ListenerAlgoOpts](/api-reference/zlb/datastructure.md#listeneralgoopts) | Advanced scheduling-algorithm option.
Can only be set when the forwarding mode (kind) is DR and the scheduling algorithm (scheduler) is mh.
Omitting this field leaves it unchanged; passing None explicitly clears an already-enabled option.
Validation is based on the final effective state after the update: if this option is already enabled on the listener, changing kind or scheduler to a combination that no longer supports it also requires passing None in the same request.
Once enabled, it is mutually exclusive with session persistence (persistent): if this option is already enabled on the listener, changing persistent to a non-zero value will also be rejected — None must be passed in the same request to clear it.
|
## 3. Output Parameters
| Parameter Name | Type | Description |
| -------------- | ------ | --------------------------------------------------------------------------------------------------------------------- |
| requestId | String | The unique request ID, which is returned for each request.
RequestId is required for locating a problem.
|
## 4. Code Example
{% tabs %}
{% tab title="Example" %}
**1. Modify the name, health check parameters, and forwarding policy of a load balancer listener.**
```json
POST /api/v2/zlb HTTP/1.1
Host: console.zenlayer.com
Content-Type: application/json
X-ZC-Action: ModifyListener
Request:
{
"loadBalancerId" : "",
"listenerId" : "",
"listenerName" : "sampleName",
"persistent": 60,
"idleTimeout": 60,
"healthCheck" : {
"enabled": true,
"checkType": "PING_CHECK",
"checkPort": null,
"checkDelayLoop": 4,
"checkConnTimeout": 3,
"checkRetry": 4,
"checkDelayTry": 5,
"checkHttpGetUrl": "/",
"checkHttpStatusCode": null
},
"scheduler" : "mh"
}
Response:
{
"requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3",
"response": {
"requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3"
}
}
```
**2. Enable stateless forwarding. `algoOpts` can be set only when the forwarding mode `kind` is `DR` and the scheduling algorithm `scheduler` is `mh`. It is mutually exclusive with session persistence `persistent`, so `persistent` must be set to 0 at the same time.**
```json
POST /api/v2/zlb HTTP/1.1
Host: console.zenlayer.com
Content-Type: application/json
X-ZC-Action: ModifyListener
Request:
{
"loadBalancerId" : "",
"listenerId" : "",
"kind": "DR",
"scheduler" : "mh",
"algoOpts": "StatelessForwarding",
"persistent": 0
}
Response:
{
"requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3",
"response": {
"requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3"
}
}
```
**3. Disable stateless forwarding and restore session persistence. Passing `None` for `algoOpts` clears the enabled advanced options.**
```json
POST /api/v2/zlb HTTP/1.1
Host: console.zenlayer.com
Content-Type: application/json
X-ZC-Action: ModifyListener
Request:
{
"loadBalancerId" : "",
"listenerId" : "",
"algoOpts": "None",
"persistent": 60
}
Response:
{
"requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3",
"response": {
"requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3"
}
}
```
{% endtab %}
{% endtabs %}
## 5. Developer Resources
Zenlayer Cloud API 2.0 integrates [SDKs](/api-reference/api-introduction/toolkit/api-sdk.md)，to make it easier for you to call APIs. More programming languages will be supported.
## 6. Error Codes
The following only lists the error codes related to the API business logic. For other error codes, see [Common Error Codes](/api-reference/api-introduction/instruction/commonerrorcode.md).
| HTTP Status Code | Error Code | Description |
| ---------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400 | INVALID\_ALGO\_OPTS\_NOT\_SUPPORTED | The advanced scheduling-algorithm option (`algoOpts`) is only supported when the forwarding mode (`kind`) is `DR` and the scheduling algorithm (`scheduler`) is `mh`. |
| 400 | INVALID\_ALGO\_OPTS\_PERSISTENT\_CONFLICT | The advanced scheduling algorithm option (stateless forwarding) and session persistence cannot be enabled simultaneously. |
| 404 | INVALID\_LB\_LISTENER\_NOT\_FOUND | The listener does not exist. |
| 409 | INVALID\_LISTENER\_KIND\_CONFLICT | The listener's forwarding mode is inconsistent with an existing listener on this load balancer. |
| 400 | INVALID\_LISTENER\_KIND\_DR\_ALL\_PORT\_NOT\_SUPPORT | A listener in DR mode does not support all-port (0). |
| 400 | INVALID\_LISTENER\_KIND\_NOT\_SUPPORT | The specified listener type is not supported in this region. |
| 409 | INVALID\_LISTENER\_PORT\_CONFLICT | The port conflicts with another listener. |
| 409 | INVALID\_LISTENER\_PORT\_CONFLICT\_SELF | The configured port is invalid due to a conflict. |
| 400 | INVALID\_PORT\_FORMAT\_ERROR | Invalid port format. |
| 400 | INVALID\_PORT\_RANGE | Invalid port range. The port range should be between 1 and 65535. |
| 400 | INVALID\_HEALTH\_CHECK\_PORT\_REQUIRED | When using TCP or HTTP health checks with an all-port listener, a health check port must be specified. |