Updated on 2022-01-25 GMT+08:00

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.

Constraints

Parameters marker, limit, and page_reverse are used for pagination query. Parameters marker and page_reverse take effect only when they are used together with parameter limit.

URI

GET /v2.0/lbaas/listeners

Request

Table 1 Parameter description

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.

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.

tenant_id

No

String

Specifies the ID of the project where the listener is used.

project_id

No

String

Specifies the ID of the project where the listener is used.

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.

default_pool_id

No

String

Specifies the ID of the associated backend server group.

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.

The value contains a maximum of 128 characters.

client_ca_tls_container_ref

No

String

Specifies the ID of the CA certificate used by the listener.

The value contains a maximum of 128 characters.

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.

tls_container_id

No

String

Queries the listener associated with the certificate.

sni_container_refs

No

String

Queries the listener associated with the SNI certificate.

Table 2 tls_ciphers_policy parameter description

Security Policy

TLS Version

Cipher Suite

tls-1-0-inherit

TLSv1.2 TLSv1.1 TLSv1

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

TLSv1.2 TLSv1.1 TLSv1

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

TLSv1.2 TLSv1.1

tls-1-2

TLSv1.2

tls-1-2-strict

TLSv1.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

Response

Table 3 Parameter description

Parameter

Type

Description

listeners

Array

Lists the listeners. For details, see Table 4.

listeners_links

Array

Provides links to the previous or next page during pagination query, respectively. This parameter exists only in the response body of pagination query. For details, see Table 7.

Table 4 listeners 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.

name

String

Specifies the listener name.

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

Specifies the ID of the associated load balancer.

connection_limit

Integer

Specifies the maximum number of connections.

The value ranges from -1 to 2147483647.

NOTE:

This parameter is reserved. The default value is -1, indicating that there is no restriction on the maximum number of connections.

admin_state_up

Boolean

Specifies the administrative status of the listener.

NOTE:

This parameter is reserved. Currently, the value can only be true.

http2_enable

Boolean

Specifies whether to use HTTP/2.

The value can be true or false.

  • true: HTTP/2 will be used.
  • false: HTTP/2 will not be used.
NOTE:

This parameter is valid only when the protocol used by the listener is set to TERMINATED_HTTPS.

keepalive_timeout

Integer

Specifies the idle timeout duration in the unit of second.

The value ranges from 1 to 300. The default value is 15.

client_timeout

Integer

Specifies the request timeout duration in the unit of second.

The value ranges from 1 to 60. The default value is 60.

This parameter is valid only when protocol is set to HTTP or HTTPS. In other cases, the request body does not contain this parameter. Otherwise, an error is reported. When protocol is set to HTTP or HTTPS, if the request body does not contain this parameter or the value of this parameter is null, the default value is used.

member_timeout

Integer

Specifies the response timeout duration in the unit of second.

The value ranges from 1 to 60. The default value is 60.

This parameter is valid only when protocol is set to HTTP or HTTPS. In other cases, the request body does not contain this parameter. Otherwise, an error is reported. When protocol is set to HTTP or HTTPS, if the request body does not contain this parameter or the value of this parameter is null, the default value is used.

default_pool_id

String

Specifies the ID of the associated backend server group.

NOTE:

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.

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.

sni_container_refs

Array

Lists the IDs of SNI certificates (server certificates with a domain name) used by the listener.

tags

Array

Tags the listener.

created_at

String

Specifies the time when the listener was created. The UTC time is in YYYY-MM-DDTHH:MM:SS format.

The value contains a maximum of 19 characters.

updated_at

String

Specifies the time when the listener was updated. The UTC time is in YYYY-MM-DDTHH:MM:SS format.

The value contains a maximum of 19 characters.

listeners_links

Array

Provides links to the previous or next page during pagination query, respectively. This parameter exists only in the response body of pagination query.

Table 5 loadbalancers parameter description

Parameter

Type

Description

id

String

Specifies the ID of the associated load balancer.

Table 6 tls_ciphers_policy parameter description

Security Policy

TLS Version

Cipher Suite

tls-1-0-inherit

TLSv1.2 TLSv1.1 TLSv1

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

TLSv1.2 TLSv1.1 TLSv1

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

TLSv1.2 TLSv1.1

tls-1-2

TLSv1.2

tls-1-2-strict

TLSv1.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

Table 7 listeners_links parameter description

Parameter

Type

Description

href

String

Provides links to the previous or next page during pagination query, respectively.

rel

String

Specifies the prompt of the previous or next page.

The value can be next or previous. The value next indicates the href containing the URL of the next page, and previous indicates the href containing the URL of the previous page.

Example Request

  • Example request 1: Querying all listeners
    GET https://{Endpoint}/v2.0/lbaas/listeners?limit=2
  • Request example 2: Querying UDP listeners
    GET https://{Endpoint}/v2.0/lbaas/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",
     
                "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",
         
                "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",
                "created_at": "2018-07-25T01:54:13", 
                "updated_at": "2018-07-25T01:54:14"
      
    ,
     
            }
        ],
        "listeners_links": [
            {
            "href": "https://{Endpoint}/v2.0/lbaas/listeners?limit=2&marker=042cc6a5-e385-4e39-83de-4dde1f801ccb",
            "rel": "next"
            },
            {
            "href": "https://{Endpoint}/v2.0/lbaas/listeners?limit=2&marker=025fcaa9-0159-4a0d-8583-d97fa77d9972&page_reverse=True",
            "rel": "previous"
            }
        ]
    }
  • Example response 2
    {
        "listeners": [
            {
                "protocol_port": 64809,
                "protocol": "UDP",
                "description": "",
                "default_tls_container_ref": null,
                "sni_container_refs": [],
                "loadbalancers": [
                    {
                        "id": "c1127125-64a9-4394-a08a-ef3be8f7ef9c"
                    }
                ],
                "tenant_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,
        
                "admin_state_up": true,
                "default_pool_id": "2f6895be-019b-4c82-9b53-c4a2ac009e20",
                "id": "5c63d176-444f-4c75-9cfe-bcb8a05a845c",
                "tags": [],
                "name": "listener-tvp8"
            }
        ]
    }

Status Code

For details, see HTTP Status Codes of Load Balancers.