Querying Listeners

Function

This API is used to query the listeners and display them in a list. Filter query and pagination query are supported. Unless otherwise specified, exact match is applied.

You can query listeners using information such as listener ID, protocol used by the listener, port used by the listener, or backend server private IP address.

URI

GET /v2/{project_id}/elb/listeners

**Table 1** Path parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Specifies the project ID.

**Table 2** Query parameters
Parameter	Mandatory	Type	Description
marker	No	String	Specifies the ID of the listener from which pagination query starts, that is, the ID of the last listener on the previous page. This parameter must be used together with limit.
limit	No	Integer	Specifies the number of listeners on each page. If this parameter is not set, all listeners are queried by default.
page_reverse	No	Boolean	Specifies the page direction. The value can be true or false, and the default value is false. The last page in the list requested with page_reverse set to false will not contain the "next" link, and the last page in the list requested with page_reverse set to true will not contain the "previous" link. This parameter must be used together with limit.
id	No	String	Specifies the listener ID.
name	No	String	Specifies the listener name. The value contains a maximum of 255 characters.
description	No	String	Provides supplementary information about the listener. The value contains a maximum of 255 characters.
loadbalancer_id	No	String	Specifies the ID of the associated load balancer.
connection_limit	No	Integer	Specifies the maximum number of connections.
admin_state_up	No	Boolean	Specifies the administrative status of the listener. This parameter is reserved, and the default value is true.
default_pool_id	No	String	Specifies the ID of the associated backend server group. If a request does not match the forwarding policy, the request is forwarded to the default backend server group for processing.
http2_enable	No	Boolean	Specifies whether to use HTTP/2. The value can be true or false. true: HTTP/2 is used. false: HTTP/2 is not used.
default_tls_container_ref	No	String	Specifies the ID of the server certificate used by the listener.
client_ca_tls_container_ref	No	String	Specifies the ID of the CA certificate used by the listener.
protocol	No	String	Specifies the protocol used by the listener. The value can be TCP, HTTP, UDP, or TERMINATED_HTTPS.
protocol_port	No	Integer	Specifies the port used by the listener.
enterprise_project_id	No	String	Specifies the enterprise project ID. Enterprise projects are used for fine-grained authentication. If default_pool_id is passed, the ID of the enterprise project to which the backend server group belongs is used for authentication. If neither default_pool_id nor enterprise_project_id is passed, fine-grained authentication is performed. The elb:loadbalancers:list permissions must be assigned to the user group.
tls_ciphers_policy	No	String	Specifies the security policy used by the listener. This parameter takes effect only when the protocol used by the listener is set to TERMINATED_HTTPS. The value can be tls-1-0-inherit, tls-1-0, tls-1-1, tls-1-2, or tls-1-2-strict, and the default value is tls-1-0. For details of cipher suites for each security policy, see Table 3.

**Table 3** **tls_ciphers_policy** parameter description
Security Policy	TLS Version	Cipher Suite
tls-1-0-inherit	TLS 1.2 TLS 1.1 TLS 1.0	ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256:AES128-GCM-SHA256:AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:AES128-SHA256:AES256-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES128-SHA:DHE-RSA-AES128-SHA:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:AES128-SHA:AES256-SHA:DHE-DSS-AES128-SHA:CAMELLIA128-SHA:EDH-RSA-DES-CBC3-SHA:DES-CBC3-SHA:ECDHE-RSA-RC4-SHA:RC4-SHA:DHE-RSA-AES256-SHA:DHE-DSS-AES256-SHA:DHE-RSA-CAMELLIA256-SHA:DHE-DSS-CAMELLIA256-SHA:CAMELLIA256-SHA:EDH-DSS-DES-CBC3-SHA:DHE-RSA-CAMELLIA128-SHA:DHE-DSS-CAMELLIA128-SHA
tls-1-0	TLS 1.2 TLS 1.1 TLS 1.0	ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256:AES128-GCM-SHA256:AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:AES128-SHA256:AES256-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES128-SHA:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:AES128-SHA:AES256-SHA
tls-1-1	TLS 1.2 TLS 1.1
tls-1-2	TLS 1.2
tls-1-2-strict	TLS 1.2	ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256:AES128-GCM-SHA256:AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:AES128-SHA256:AES256-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384

Request

None

Response

**Table 4** Response parameters
Parameter	Type	Description
listeners	Array of Listeners objects	Lists the listeners. For details, see Table 5.

**Table 5** **listener** parameter description
Parameter	Type	Description
id	String	Specifies the listener ID.
tenant_id	String	Specifies the ID of the project where the listener is used. The value contains a maximum of 255 characters.
project_id	String	Specifies the ID of the project to which the listener belongs. This parameter has the same meaning as tenant_id.
name	String	Specifies the listener name. Note: If you leave the listener name empty, you cannot locate it on the listener list and view its details. The value contains a maximum of 255 characters.
description	String	Provides supplementary information about the listener. The value contains a maximum of 255 characters.
protocol	String	Specifies the protocol used by the listener. The value can be TCP, HTTP, UDP, or TERMINATED_HTTPS.
protocol_port	Integer	Specifies the port used by the listener. The port number ranges from 1 to 65535.
loadbalancers	Array of Loadbalancers objects	Specifies the ID of the associated load balancer. For details, see Table 8.
connection_limit	Integer	Specifies the maximum number of connections. The value ranges from -1 to 2147483647. The default value is -1, indicating that there is no restriction on the maximum number of connections. This parameter is reserved.
admin_state_up	Boolean	Specifies the administrative status of the listener. This parameter is reserved. The value can be true or false. true: Enabled false: Disabled
http2_enable	Boolean	Specifies whether to use HTTP/2. The value can be true or false. true: HTTP/2 is used. false: HTTP/2 is not used. This parameter takes effect only when the protocol used by the listener is set to TERMINATED_HTTPS.
default_pool_id	String	Specifies the ID of the associated backend server group. If a request does not match the forwarding policy, the request is forwarded to the default backend server group for processing. If the value is null, the listener has no default backend server group.
default_tls_container_ref	String	Specifies the ID of the server certificate used by the listener. For details, see Certificate. This parameter is mandatory when protocol is set to TERMINATED_HTTPS. The value contains a maximum of 128 characters.
client_ca_tls_container_ref	String	Specifies the ID of the CA certificate used by the listener. The value contains a maximum of 128 characters. For details, see Certificate.
sni_container_refs	Array	Lists the IDs of SNI certificates (server certificates with domain names) used by the listener. If the parameter value is an empty list, the SNI feature is disabled.
tags	Array	Tags the listener.
created_at	String	Specifies the time when the listener was created. YYYY-MM-DDTHH:MM:SS
updated_at	String	Specifies the time when the listener was updated. YYYY-MM-DDTHH:MM:SS
insert_headers	InsertHeaders object	Specifies whether to insert HTTP extension headers and sent them to backend servers. All headers are synchronized. If this parameter is not set, default values are used. Information required by backend servers can be written into HTTP headers and passed to backend servers. For example, you can use the X-Forwarded-ELB-IP header to transmit the load balancer EIP to backend servers. For details, see Table 9.
tls_ciphers_policy	String	Specifies the security policy used by the listener. This parameter takes effect only when the protocol used by the listener is set to TERMINATED_HTTPS. The value can be tls-1-0-inherit, tls-1-0, tls-1-1, tls-1-2, or tls-1-2-strict, and the default value is tls-1-0. Lists cipher suites used by each security policy. For details, see Table 10.
protection_status	String	String Specifies whether modification protection is enabled. The value can be one of the following: nonProtection (default) : Modification protection is not enabled. consoleProtection: Modification protection is enabled to avoid that resources are modified by accident on the console.
protection_reason	String	String Specifies the reason to enable modification protection. This parameter is valid only when protection_status is set to consoleProtection.

**Table 6** **loadbalancers** parameter description
Parameter	Mandatory	Type	Description
id	Yes	String	Specifies the ID of the associated load balancer.

**Table 7** **insert_headers** parameter description
Parameter	Mandatory	Type	Description
X-Forwarded-ELB-IP	No	Boolean	Specifies whether to transparently transmit the load balancer EIP to backend servers. After this function is enabled, the load balancer EIP is stored in the HTTP header and passes to backend servers. The value can be true or false. true: This function is enabled. false: The function is disabled. The function is disabled by default.
X-Forwarded-Host	No	Boolean	Specifies whether to rewrite the X-Forwarded-Host header. If this function is enabled, X-Forwarded-Host is rewritten based on Host in the request and sent to backend servers. The value can be true or false. true: This function is enabled. false: The function is disabled. The function is enabled by default.

**Table 8** **tls_ciphers_policy** parameter description
Security Policy	TLS Version	Cipher Suite
tls-1-0-inherit	TLS 1.2 TLS 1.1 TLS 1.0	ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256:AES128-GCM-SHA256:AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:AES128-SHA256:AES256-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES128-SHA:DHE-RSA-AES128-SHA:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:AES128-SHA:AES256-SHA:DHE-DSS-AES128-SHA:CAMELLIA128-SHA:EDH-RSA-DES-CBC3-SHA:DES-CBC3-SHA:ECDHE-RSA-RC4-SHA:RC4-SHA:DHE-RSA-AES256-SHA:DHE-DSS-AES256-SHA:DHE-RSA-CAMELLIA256-SHA:DHE-DSS-CAMELLIA256-SHA:CAMELLIA256-SHA:EDH-DSS-DES-CBC3-SHA:DHE-RSA-CAMELLIA128-SHA:DHE-DSS-CAMELLIA128-SHA
tls-1-0	TLS 1.2 TLS 1.1 TLS 1.0	ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256:AES128-GCM-SHA256:AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:AES128-SHA256:AES256-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES128-SHA:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:AES128-SHA:AES256-SHA
tls-1-1	TLS 1.2 TLS 1.1
tls-1-2	TLS 1.2
tls-1-2-strict	TLS 1.2	ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256:AES128-GCM-SHA256:AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:AES128-SHA256:AES256-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384

Example Request

Example request 1: Querying all listeners

GET https://{Endpoint}/v2/601240b9c5c94059b63d484c92cfe308/elb/listeners

Request example 2: Querying UDP listeners

GET https://{Endpoint}/v2/601240b9c5c94059b63d484c92cfe308/elb/listeners?protocol=UDP

Example Response

Example response 1

{
    "listeners": [
        {
            "client_ca_tls_container_ref": null,
            "protocol": "TCP",
            "description": "",
            "default_tls_container_ref": null,
            "admin_state_up": true,
            "http2_enable": false,
            "loadbalancers": [
                {
                    "id": "bc7ba445-035a-4464-a1a3-a62cf4a14116"
                }
            ],
            "tenant_id": "601240b9c5c94059b63d484c92cfe308",
            "project_id": "601240b9c5c94059b63d484c92cfe308",
            "sni_container_refs": [],       
 
            "connection_limit": -1,
            "protocol_port": 80,
            "default_pool_id": "ed75f16e-fcc6-403e-a3fb-4eae82005eab",
            "id": "75045172-70e9-480d-9443-b8b6459948f7",
            "tags": [],
            "name": "listener-cb2n",
            "insert_headers":{
                "X-Forwarded-ELB-IP":true,
                "X-Forwarded-Host":true
            },
            "created_at": "2018-07-25T01:54:13", 
            "updated_at": "2018-07-25T01:54:14"
        },
        {
            "client_ca_tls_container_ref": null,
            "protocol": "TCP",
            "description": "",
            "default_tls_container_ref": null,
            "admin_state_up": true,
            "http2_enable": false,
            "loadbalancers": [
                {
                    "id": "165b6a38-5278-4569-b747-b2ee65ea84a4"
                }
            ],
            "tenant_id": "601240b9c5c94059b63d484c92cfe308",
            "sni_container_refs": [],           
 
            "connection_limit": -1,
            "protocol_port": 8080,
            "default_pool_id": null,
            "id": "dada0003-7b0e-4de8-a4e1-1e937be2ba14",
            "tags": [],
            "name": "lsnr_name_mod",
            "insert_headers":{
                "X-Forwarded-ELB-IP":true,
                "X-Forwarded-Host":true
            },
            "created_at": "2018-07-25T01:54:13", 
            "updated_at": "2018-07-25T01:54:14"
        }
    ]
}

Example response 2

{
    "listeners": [
        {
            "insert_headers": null,
            "protocol_port": 64809,
            "protocol": "UDP",
            "description": "",
            "default_tls_container_ref": null,
            "sni_container_refs": [],
            "loadbalancers": [
                {
                    "id": "c1127125-64a9-4394-a08a-ef3be8f7ef9c"
                }
            ],
            "tenant_id": "601240b9c5c94059b63d484c92cfe308",
            "project_id": "601240b9c5c94059b63d484c92cfe308",
            "created_at": "2018-11-29T13:56:21",
            "client_ca_tls_container_ref": null,
            "connection_limit": -1,
            "updated_at": "2018-11-29T13:56:22",
            "http2_enable": false,
            "insert_headers":{
                "X-Forwarded-ELB-IP":true,
                "X-Forwarded-Host":true
            },
 
            "admin_state_up": true,
            "default_pool_id": "2f6895be-019b-4c82-9b53-c4a2ac009e20",
            "id": "5c63d176-444f-4c75-9cfe-bcb8a05a845c",
            "tags": [],
            "name": "listener-tvp8"
        }
    ]
}