"Fossies" - the Fresh Open Source Software Archive

Member "octavia-8.0.0/api-ref/source/v2/listener.inc" (14 Apr 2021, 20203 Bytes) of package /linux/misc/openstack/octavia-8.0.0.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) fasm source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. For more information about "listener.inc" see the Fossies "Dox" file reference documentation and the latest Fossies "Diffs" side-by-side code changes report: 7.1.1_vs_8.0.0.

    1 .. -*- rst -*-
    2 
    3 List Listeners
    4 ==============
    5 
    6 .. rest_method:: GET /v2/lbaas/listeners
    7 
    8 Lists all listeners for the project.
    9 
   10 Use the ``fields`` query parameter to control which fields are
   11 returned in the response body. Additionally, you can filter results
   12 by using query string parameters. For information, see :ref:`filtering`.
   13 
   14 Administrative users can specify a project ID that is different than their own
   15 to list listeners for other projects.
   16 
   17 The list might be empty.
   18 
   19 .. rest_status_code:: success ../http-status.yaml
   20 
   21    - 200
   22 
   23 .. rest_status_code:: error ../http-status.yaml
   24 
   25    - 400
   26    - 401
   27    - 500
   28 
   29 Request
   30 -------
   31 
   32 .. rest_parameters:: ../parameters.yaml
   33 
   34    - fields: fields
   35    - project_id: project_id_query
   36 
   37 Curl Example
   38 ------------
   39 
   40 .. literalinclude:: examples/listeners-list-curl
   41    :language: bash
   42 
   43 Response Parameters
   44 -------------------
   45 
   46 .. rest_parameters:: ../parameters.yaml
   47 
   48    - admin_state_up: admin_state_up
   49    - allowed_cidrs: allowed_cidrs
   50    - alpn_protocols: alpn_protocols-listener
   51    - client_authentication: client_authentication
   52    - client_ca_tls_container_ref: client_ca_tls_container_ref
   53    - client_crl_container_ref: client_crl_container_ref
   54    - connection_limit: connection_limit
   55    - created_at: created_at
   56    - default_pool_id: default_pool_id
   57    - default_tls_container_ref: default_tls_container_ref
   58    - description: description
   59    - id: listener-id
   60    - insert_headers: insert_headers
   61    - l7policies: l7policy-ids
   62    - listener: listener
   63    - loadbalancers: loadbalancer-ids
   64    - name: name
   65    - operating_status: operating_status
   66    - project_id: project_id
   67    - protocol: protocol
   68    - protocol_port: protocol_port
   69    - provisioning_status: provisioning_status
   70    - sni_container_refs: sni_container_refs
   71    - tags: tags
   72    - timeout_client_data: timeout_client_data
   73    - timeout_member_connect: timeout_member_connect
   74    - timeout_member_data: timeout_member_data
   75    - timeout_tcp_inspect: timeout_tcp_inspect
   76    - tls_ciphers: tls_ciphers
   77    - tls_versions: tls_versions
   78    - updated_at: updated_at
   79 
   80 Response Example
   81 ----------------
   82 
   83 .. literalinclude:: examples/listeners-list-response.json
   84    :language: javascript
   85 
   86 Create Listener
   87 ===============
   88 
   89 .. rest_method:: POST /v2/lbaas/listeners
   90 
   91 Creates a listener for a load balancer.
   92 
   93 The listener configures a port and protocol for the load balancer to listen
   94 on for incoming requests.  A load balancer may have zero or more listeners
   95 configured.
   96 
   97 This operation provisions a new listener by using the configuration that
   98 you define in the request object. After the API validates the request and
   99 starts the provisioning process, the API returns a response object that
  100 contains a unique ID and the status of provisioning the listener.
  101 
  102 In the response, the listener :ref:`provisioning status<prov_status>` is
  103 ``ACTIVE``, ``PENDING_CREATE``, or ``ERROR``.
  104 
  105 If the status is ``PENDING_CREATE``, issue GET
  106 ``/v2/lbaas/listeners/{listener_id}`` to view the progress of
  107 the provisioning operation. When the listener status changes
  108 to ``ACTIVE``, the listener is successfully provisioned and
  109 is ready for further configuration.
  110 
  111 If the API cannot fulfill the request due to insufficient data or
  112 data that is not valid, the service returns the HTTP ``Bad Request
  113 (400)`` response code with information about the failure in the
  114 response body. Validation errors require that you correct the error
  115 and submit the request again.
  116 
  117 Specifying a project_id is deprecated.  The listener will inherit
  118 the project_id of the parent load balancer.
  119 
  120 You can configure all documented features of the listener at creation time by
  121 specifying the additional elements or attributes in the request.
  122 
  123 To create a listener, the parent load balancer must have an ``ACTIVE``
  124 provisioning status.
  125 
  126 .. rest_status_code:: success ../http-status.yaml
  127 
  128    - 201
  129 
  130 .. rest_status_code:: error ../http-status.yaml
  131 
  132    - 400
  133    - 401
  134    - 403
  135    - 404
  136    - 409
  137    - 500
  138    - 503
  139 
  140 Request
  141 -------
  142 
  143 .. rest_parameters:: ../parameters.yaml
  144 
  145    - admin_state_up: admin_state_up-default-optional
  146    - allowed_cidrs: allowed_cidrs-optional
  147    - alpn_protocols: alpn_protocols-listener-optional
  148    - client_authentication: client_authentication-optional
  149    - client_ca_tls_container_ref: client_ca_tls_container_ref-optional
  150    - client_crl_container_ref: client_crl_container_ref-optional
  151    - connection_limit: connection_limit-optional
  152    - default_pool: pool-optional
  153    - default_pool_id: default_pool_id-optional
  154    - default_tls_container_ref: default_tls_container_ref-optional
  155    - description: description-optional
  156    - insert_headers: insert_headers-optional
  157    - l7policies: l7policies-optional
  158    - listeners: listener
  159    - loadbalancer_id: loadbalancer-id
  160    - name: name-optional
  161    - project_id: project_id-optional-deprecated
  162    - protocol: protocol
  163    - protocol_port: protocol_port
  164    - sni_container_refs: sni_container_refs-optional
  165    - tags: tags-optional
  166    - timeout_client_data: timeout_client_data-optional
  167    - timeout_member_connect: timeout_member_connect-optional
  168    - timeout_member_data: timeout_member_data-optional
  169    - timeout_tcp_inspect: timeout_tcp_inspect-optional
  170    - tls_ciphers: tls_ciphers-optional
  171    - tls_versions: tls_versions-optional
  172 
  173 .. _header_insertions:
  174 
  175 Supported HTTP Header Insertions
  176 --------------------------------
  177 
  178 .. note::
  179    Both the key and the values are always specified as strings when specifying
  180    header insertions.
  181 
  182 
  183 +-------------------------+--------+------------------------------------------------+
  184 | Key                     | Value  | Description                                    |
  185 +=========================+========+================================================+
  186 | X-Forwarded-For         | string | When "``true``" a ``X-Forwarded-For`` header   |
  187 |                         |        | is inserted into the request to the backend    |
  188 |                         |        | ``member`` that specifies the client IP        |
  189 |                         |        | address.                                       |
  190 +-------------------------+--------+------------------------------------------------+
  191 | X-Forwarded-Port        | string | When "``true``" a ``X-Forwarded-Port`` header  |
  192 |                         |        | is inserted into the request to the backend    |
  193 |                         |        | ``member`` that specifies the listener port.   |
  194 +-------------------------+--------+------------------------------------------------+
  195 | X-Forwarded-Proto       | string | When "``true``" a ``X-Forwarded-Proto`` header |
  196 |                         |        | is inserted into the request to the backend    |
  197 |                         |        | ``member``. HTTP for the HTTP listener         |
  198 |                         |        | protocol type, HTTPS for the TERMINATED_HTTPS  |
  199 |                         |        | listener protocol type.                        |
  200 |                         |        | **New in version 2.1**                         |
  201 +-------------------------+--------+------------------------------------------------+
  202 | X-SSL-Client-Verify     | string | When "``true``" a ``X-SSL-Client-Verify``      |
  203 |                         |        | header is inserted into the request to the     |
  204 |                         |        | backend ``member`` that contains 0 if the      |
  205 |                         |        | client authentication was successful, or an    |
  206 |                         |        | result error number greater than 0 that align  |
  207 |                         |        | to the openssl veryify error codes.            |
  208 +-------------------------+--------+------------------------------------------------+
  209 | X-SSL-Client-Has-Cert   | string | When "``true``" a ``X-SSL-Client-Has-Cert``    |
  210 |                         |        | header is inserted into the request to the     |
  211 |                         |        | backend ``member`` that is ''true'' if a client|
  212 |                         |        | authentication certificate was presented, and  |
  213 |                         |        | ''false'' if not. Does not indicate validity.  |
  214 +-------------------------+--------+------------------------------------------------+
  215 | X-SSL-Client-DN         | string | When "``true``" a ``X-SSL-Client-DN`` header   |
  216 |                         |        | is inserted into the request to the backend    |
  217 |                         |        | ``member`` that contains the full              |
  218 |                         |        | Distinguished Name of the certificate          |
  219 |                         |        | presented by the client.                       |
  220 +-------------------------+--------+------------------------------------------------+
  221 | X-SSL-Client-CN         | string | When "``true``" a ``X-SSL-Client-CN`` header   |
  222 |                         |        | is inserted into the request to the backend    |
  223 |                         |        | ``member`` that contains the Common Name from  |
  224 |                         |        | the full Distinguished Name of the certificate |
  225 |                         |        | presented by the client.                       |
  226 +-------------------------+--------+------------------------------------------------+
  227 | X-SSL-Issuer            | string | When "``true``" a ``X-SSL-Issuer`` header is   |
  228 |                         |        | inserted into the request to the backend       |
  229 |                         |        | ``member`` that contains the full              |
  230 |                         |        | Distinguished Name of the client certificate   |
  231 |                         |        | issuer.                                        |
  232 +-------------------------+--------+------------------------------------------------+
  233 | X-SSL-Client-SHA1       | string | When "``true``" a ``X-SSL-Client-SHA1`` header |
  234 |                         |        | is inserted into the request to the backend    |
  235 |                         |        | ``member`` that contains the SHA-1 fingerprint |
  236 |                         |        | of the certificate presented by the client in  |
  237 |                         |        | hex string format.                             |
  238 +-------------------------+--------+------------------------------------------------+
  239 | X-SSL-Client-Not-Before | string | When "``true``" a ``X-SSL-Client-Not-Before``  |
  240 |                         |        | header is inserted into the request to the     |
  241 |                         |        | backend ``member`` that contains the start     |
  242 |                         |        | date presented by the client as a formatted    |
  243 |                         |        | string YYMMDDhhmmss[Z].                        |
  244 +-------------------------+--------+------------------------------------------------+
  245 | X-SSL-Client-Not-After  | string | When "``true``" a ``X-SSL-Client-Not-After``   |
  246 |                         |        | header is inserted into the request to the     |
  247 |                         |        | backend ``member`` that contains the end date  |
  248 |                         |        | presented by the client as a formatted string  |
  249 |                         |        | YYMMDDhhmmss[Z].                               |
  250 +-------------------------+--------+------------------------------------------------+
  251 
  252 Request Example
  253 ----------------
  254 
  255 .. literalinclude:: examples/listener-create-request.json
  256    :language: javascript
  257 
  258 Curl Example
  259 ------------
  260 
  261 .. literalinclude:: examples/listener-create-curl
  262    :language: bash
  263 
  264 Response Parameters
  265 -------------------
  266 
  267 .. rest_parameters:: ../parameters.yaml
  268 
  269    - admin_state_up: admin_state_up
  270    - allowed_cidrs: allowed_cidrs
  271    - alpn_protocols: alpn_protocols-listener
  272    - client_authentication: client_authentication
  273    - client_ca_tls_container_ref: client_ca_tls_container_ref
  274    - client_crl_container_ref: client_crl_container_ref
  275    - connection_limit: connection_limit
  276    - created_at: created_at
  277    - default_pool_id: default_pool_id
  278    - default_tls_container_ref: default_tls_container_ref
  279    - description: description
  280    - id: listener-id
  281    - insert_headers: insert_headers
  282    - l7policies: l7policy-ids
  283    - listener: listener
  284    - loadbalancers: loadbalancer-ids
  285    - name: name
  286    - operating_status: operating_status
  287    - project_id: project_id
  288    - protocol: protocol
  289    - protocol_port: protocol_port
  290    - provisioning_status: provisioning_status
  291    - sni_container_refs: sni_container_refs
  292    - tags: tags
  293    - timeout_client_data: timeout_client_data
  294    - timeout_member_connect: timeout_member_connect
  295    - timeout_member_data: timeout_member_data
  296    - timeout_tcp_inspect: timeout_tcp_inspect
  297    - tls_ciphers: tls_ciphers
  298    - tls_versions: tls_versions
  299    - updated_at: updated_at
  300 
  301 Response Example
  302 ----------------
  303 
  304 .. literalinclude:: examples/listener-create-response.json
  305    :language: javascript
  306 
  307 Show Listener details
  308 =====================
  309 
  310 .. rest_method:: GET /v2/lbaas/listeners/{listener_id}
  311 
  312 Shows the details of a listener.
  313 
  314 If you are not an administrative user and the parent load balancer does not
  315 belong to your project, the service returns the HTTP ``Forbidden (403)``
  316 response code.
  317 
  318 This operation does not require a request body.
  319 
  320 .. rest_status_code:: success ../http-status.yaml
  321 
  322    - 200
  323 
  324 .. rest_status_code:: error ../http-status.yaml
  325 
  326    - 401
  327    - 403
  328    - 404
  329    - 500
  330 
  331 Request
  332 -------
  333 
  334 .. rest_parameters:: ../parameters.yaml
  335 
  336    - fields: fields
  337    - listener_id: path-listener-id
  338 
  339 Curl Example
  340 ------------
  341 
  342 .. literalinclude:: examples/listener-show-curl
  343    :language: bash
  344 
  345 Response Parameters
  346 -------------------
  347 
  348 .. rest_parameters:: ../parameters.yaml
  349 
  350    - admin_state_up: admin_state_up
  351    - allowed_cidrs: allowed_cidrs
  352    - alpn_protocols: alpn_protocols-listener
  353    - client_authentication: client_authentication
  354    - client_ca_tls_container_ref: client_ca_tls_container_ref
  355    - client_crl_container_ref: client_crl_container_ref
  356    - connection_limit: connection_limit
  357    - created_at: created_at
  358    - default_pool_id: default_pool_id
  359    - default_tls_container_ref: default_tls_container_ref
  360    - description: description
  361    - id: listener-id
  362    - insert_headers: insert_headers
  363    - l7policies: l7policy-ids
  364    - listener: listener
  365    - loadbalancers: loadbalancer-ids
  366    - name: name
  367    - operating_status: operating_status
  368    - project_id: project_id
  369    - protocol: protocol
  370    - protocol_port: protocol_port
  371    - provisioning_status: provisioning_status
  372    - sni_container_refs: sni_container_refs
  373    - tags: tags
  374    - timeout_client_data: timeout_client_data
  375    - timeout_member_connect: timeout_member_connect
  376    - timeout_member_data: timeout_member_data
  377    - timeout_tcp_inspect: timeout_tcp_inspect
  378    - tls_ciphers: tls_ciphers
  379    - tls_versions: tls_versions
  380    - updated_at: updated_at
  381 
  382 Response Example
  383 ----------------
  384 
  385 .. literalinclude:: examples/listener-show-response.json
  386    :language: javascript
  387 
  388 Update a Listener
  389 =================
  390 
  391 .. rest_method:: PUT /v2/lbaas/listeners/{listener_id}
  392 
  393 Update an existing listener.
  394 
  395 If the request is valid, the service returns the ``Accepted (202)``
  396 response code. To confirm the update, check that the listener provisioning
  397 status is ``ACTIVE``. If the status is ``PENDING_UPDATE``, use a GET
  398 operation to poll the listener object for changes.
  399 
  400 This operation returns the updated listener object with the
  401 ``ACTIVE``, ``PENDING_UPDATE``, or ``ERROR`` provisioning status.
  402 
  403 .. rest_status_code:: success ../http-status.yaml
  404 
  405    - 202
  406 
  407 .. rest_status_code:: error ../http-status.yaml
  408 
  409    - 400
  410    - 401
  411    - 403
  412    - 404
  413    - 409
  414    - 500
  415 
  416 Request
  417 -------
  418 
  419 .. rest_parameters:: ../parameters.yaml
  420 
  421    - admin_state_up: admin_state_up-default-optional
  422    - allowed_cidrs: allowed_cidrs-optional
  423    - alpn_protocols: alpn_protocols-listener-optional
  424    - client_authentication: client_authentication-optional
  425    - client_ca_tls_container_ref: client_ca_tls_container_ref-optional
  426    - client_crl_container_ref: client_crl_container_ref-optional
  427    - connection_limit: connection_limit-optional
  428    - default_pool_id: default_pool_id-optional
  429    - default_tls_container_ref: default_tls_container_ref-optional
  430    - description: description-optional
  431    - insert_headers: insert_headers-optional
  432    - listener_id: path-listener-id
  433    - name: name-optional
  434    - sni_container_refs: sni_container_refs-optional
  435    - tags: tags-optional
  436    - timeout_client_data: timeout_client_data-optional
  437    - timeout_member_connect: timeout_member_connect-optional
  438    - timeout_member_data: timeout_member_data-optional
  439    - timeout_tcp_inspect: timeout_tcp_inspect-optional
  440    - tls_ciphers: tls_ciphers-optional
  441    - tls_versions: tls_versions-optional
  442 
  443 Request Example
  444 ---------------
  445 
  446 .. literalinclude:: examples/listener-update-request.json
  447    :language: javascript
  448 
  449 Curl Example
  450 ------------
  451 
  452 .. literalinclude:: examples/listener-update-curl
  453    :language: bash
  454 
  455 Response Parameters
  456 -------------------
  457 
  458 .. rest_parameters:: ../parameters.yaml
  459 
  460    - admin_state_up: admin_state_up
  461    - allowed_cidrs: allowed_cidrs
  462    - alpn_protocols: alpn_protocols-listener
  463    - client_authentication: client_authentication
  464    - client_ca_tls_container_ref: client_ca_tls_container_ref
  465    - client_crl_container_ref: client_crl_container_ref
  466    - connection_limit: connection_limit
  467    - created_at: created_at
  468    - default_pool_id: default_pool_id
  469    - default_tls_container_ref: default_tls_container_ref
  470    - description: description
  471    - id: listener-id
  472    - insert_headers: insert_headers
  473    - l7policies: l7policy-ids
  474    - listener: listener
  475    - loadbalancers: loadbalancer-ids
  476    - name: name
  477    - operating_status: operating_status
  478    - project_id: project_id
  479    - protocol: protocol
  480    - protocol_port: protocol_port
  481    - provisioning_status: provisioning_status
  482    - sni_container_refs: sni_container_refs
  483    - tags: tags
  484    - timeout_client_data: timeout_client_data
  485    - timeout_member_connect: timeout_member_connect
  486    - timeout_member_data: timeout_member_data
  487    - timeout_tcp_inspect: timeout_tcp_inspect
  488    - tls_ciphers: tls_ciphers
  489    - tls_versions: tls_versions
  490    - updated_at: updated_at
  491 
  492 Response Example
  493 ----------------
  494 
  495 .. literalinclude:: examples/listener-update-response.json
  496    :language: javascript
  497 
  498 Remove a Listener
  499 =================
  500 
  501 .. rest_method:: DELETE /v2/lbaas/listeners/{listener_id}
  502 
  503 Removes a listener and its associated configuration from the project.
  504 
  505 The API immediately purges any and all configuration data, depending on the
  506 configuration settings. You cannot recover it.
  507 
  508 .. rest_status_code:: success ../http-status.yaml
  509 
  510    - 204
  511 
  512 .. rest_status_code:: error ../http-status.yaml
  513 
  514    - 400
  515    - 401
  516    - 403
  517    - 404
  518    - 409
  519    - 500
  520 
  521 Request
  522 -------
  523 
  524 .. rest_parameters:: ../parameters.yaml
  525 
  526    - listener_id: path-listener-id
  527 
  528 Curl Example
  529 ------------
  530 
  531 .. literalinclude:: examples/listener-delete-curl
  532    :language: bash
  533 
  534 Response
  535 --------
  536 
  537 There is no body content for the response of a successful DELETE request.
  538 
  539 Get Listener statistics
  540 =======================
  541 
  542 .. rest_method:: GET /v2/lbaas/listeners/{listener_id}/stats
  543 
  544 Shows the current statistics for a listener.
  545 
  546 This operation returns the statistics of a listener object identified
  547 by listener_id.
  548 
  549 If you are not an administrative user and the parent load balancer does not
  550 belong to your project, the service returns the HTTP ``Forbidden (403)``
  551 response code.
  552 
  553 This operation does not require a request body.
  554 
  555 .. rest_status_code:: success ../http-status.yaml
  556 
  557    - 200
  558 
  559 .. rest_status_code:: error ../http-status.yaml
  560 
  561    - 401
  562    - 403
  563    - 404
  564    - 500
  565 
  566 Request
  567 -------
  568 
  569 .. rest_parameters:: ../parameters.yaml
  570 
  571    - listener_id: path-listener-id
  572 
  573 Curl Example
  574 ------------
  575 
  576 .. literalinclude:: examples/listener-stats-curl
  577    :language: bash
  578 
  579 Response Parameters
  580 -------------------
  581 
  582 .. rest_parameters:: ../parameters.yaml
  583 
  584    - stats: stats
  585    - active_connections: active_connections
  586    - bytes_in: bytes_in
  587    - bytes_out: bytes_out
  588    - request_errors: request_errors
  589    - total_connections: total_connections
  590 
  591 Response Example
  592 ----------------
  593 
  594 .. literalinclude:: examples/listener-stats-response.json
  595    :language: javascript