HAProxy Bind API

openapi: 3.2.0
info:
  title: HAProxy Data Plane Bind API
  description: 'API for editing and managing haproxy instances. Provides process information, configuration management,

    haproxy stats and logs.'
  version: '3.4'
  contact:
    name: HAProxy Support
    url: https://my.haproxy.com/portal/cust/login
    email: support@haproxy.com
servers:
- url: /v3
security:
- basic_auth: []
tags:
- name: Bind
  description: Managing frontend bind configurations (advanced mode)
paths:
  /services/haproxy/configuration/frontends/{parent_name}/binds:
    get:
      description: Returns an array of all binds that are configured in specified frontend.
      operationId: getAllBindFrontend
      parameters:
      - $ref: '#/components/parameters/parent_name'
      - $ref: '#/components/parameters/transaction_id'
      responses:
        '200':
          description: Successful operation
          headers:
            Configuration-Version:
              description: Configuration file version
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/binds'
        default:
          $ref: '#/components/responses/DefaultError'
      summary: Return an array of binds
      tags:
      - Bind
    post:
      description: Adds a new bind in the specified frontend in the configuration file.
      operationId: createBindFrontend
      parameters:
      - $ref: '#/components/parameters/parent_name'
      - $ref: '#/components/parameters/transaction_id'
      - $ref: '#/components/parameters/version'
      - $ref: '#/components/parameters/force_reload'
      responses:
        '201':
          description: Bind created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bind'
        '202':
          description: Configuration change accepted and reload requested
          headers:
            Reload-ID:
              description: ID of the requested reload
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bind'
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          $ref: '#/components/responses/AlreadyExists'
        default:
          $ref: '#/components/responses/DefaultError'
      summary: Add a new bind
      tags:
      - Bind
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/bind'
        required: true
  /services/haproxy/configuration/log_forwards/{parent_name}/binds:
    get:
      description: Returns an array of all binds that are configured in specified frontend.
      operationId: getAllBindLogForward
      parameters:
      - $ref: '#/components/parameters/parent_name'
      - $ref: '#/components/parameters/transaction_id'
      responses:
        '200':
          description: Successful operation
          headers:
            Configuration-Version:
              description: Configuration file version
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/binds'
        default:
          $ref: '#/components/responses/DefaultError'
      summary: Return an array of binds
      tags:
      - Bind
    post:
      description: Adds a new bind in the specified frontend in the configuration file.
      operationId: createBindLogForward
      parameters:
      - $ref: '#/components/parameters/parent_name'
      - $ref: '#/components/parameters/transaction_id'
      - $ref: '#/components/parameters/version'
      - $ref: '#/components/parameters/force_reload'
      responses:
        '201':
          description: Bind created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bind'
        '202':
          description: Configuration change accepted and reload requested
          headers:
            Reload-ID:
              description: ID of the requested reload
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bind'
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          $ref: '#/components/responses/AlreadyExists'
        default:
          $ref: '#/components/responses/DefaultError'
      summary: Add a new bind
      tags:
      - Bind
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/bind'
        required: true
  /services/haproxy/configuration/peers/{parent_name}/binds:
    get:
      description: Returns an array of all binds that are configured in specified frontend.
      operationId: getAllBindPeer
      parameters:
      - $ref: '#/components/parameters/parent_name'
      - $ref: '#/components/parameters/transaction_id'
      responses:
        '200':
          description: Successful operation
          headers:
            Configuration-Version:
              description: Configuration file version
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/binds'
        default:
          $ref: '#/components/responses/DefaultError'
      summary: Return an array of binds
      tags:
      - Bind
    post:
      description: Adds a new bind in the specified frontend in the configuration file.
      operationId: createBindPeer
      parameters:
      - $ref: '#/components/parameters/parent_name'
      - $ref: '#/components/parameters/transaction_id'
      - $ref: '#/components/parameters/version'
      - $ref: '#/components/parameters/force_reload'
      responses:
        '201':
          description: Bind created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bind'
        '202':
          description: Configuration change accepted and reload requested
          headers:
            Reload-ID:
              description: ID of the requested reload
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bind'
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          $ref: '#/components/responses/AlreadyExists'
        default:
          $ref: '#/components/responses/DefaultError'
      summary: Add a new bind
      tags:
      - Bind
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/bind'
        required: true
  /services/haproxy/configuration/frontends/{parent_name}/binds/{name}:
    delete:
      description: Deletes a bind configuration by it's name in the specified frontend.
      operationId: deleteBindFrontend
      parameters:
      - description: Bind name
        in: path
        name: name
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/parent_name'
      - $ref: '#/components/parameters/transaction_id'
      - $ref: '#/components/parameters/version'
      - $ref: '#/components/parameters/force_reload'
      responses:
        '202':
          description: Configuration change accepted and reload requested
          headers:
            Reload-ID:
              description: ID of the requested reload
              schema:
                type: string
        '204':
          description: Bind deleted
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/DefaultError'
      summary: Delete a bind
      tags:
      - Bind
    get:
      description: Returns one bind configuration by it's name in the specified frontend.
      operationId: getBindFrontend
      parameters:
      - description: Bind name
        in: path
        name: name
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/parent_name'
      - $ref: '#/components/parameters/transaction_id'
      responses:
        '200':
          description: Successful operation
          headers:
            Configuration-Version:
              description: Configuration file version
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bind'
        '404':
          $ref: '#/components/responses/AlreadyExists'
        default:
          $ref: '#/components/responses/DefaultError'
      summary: Return one bind
      tags:
      - Bind
    put:
      description: Replaces a bind configuration by it's name in the specified frontend.
      operationId: replaceBindFrontend
      parameters:
      - description: Bind name
        in: path
        name: name
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/parent_name'
      - $ref: '#/components/parameters/transaction_id'
      - $ref: '#/components/parameters/version'
      - $ref: '#/components/parameters/force_reload'
      responses:
        '200':
          description: Bind replaced
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bind'
        '202':
          description: Configuration change accepted and reload requested
          headers:
            Reload-ID:
              description: ID of the requested reload
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bind'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/DefaultError'
      summary: Replace a bind
      tags:
      - Bind
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/bind'
        required: true
  /services/haproxy/configuration/log_forwards/{parent_name}/binds/{name}:
    delete:
      description: Deletes a bind configuration by it's name in the specified frontend.
      operationId: deleteBindLogForward
      parameters:
      - description: Bind name
        in: path
        name: name
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/parent_name'
      - $ref: '#/components/parameters/transaction_id'
      - $ref: '#/components/parameters/version'
      - $ref: '#/components/parameters/force_reload'
      responses:
        '202':
          description: Configuration change accepted and reload requested
          headers:
            Reload-ID:
              description: ID of the requested reload
              schema:
                type: string
        '204':
          description: Bind deleted
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/DefaultError'
      summary: Delete a bind
      tags:
      - Bind
    get:
      description: Returns one bind configuration by it's name in the specified frontend.
      operationId: getBindLogForward
      parameters:
      - description: Bind name
        in: path
        name: name
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/parent_name'
      - $ref: '#/components/parameters/transaction_id'
      responses:
        '200':
          description: Successful operation
          headers:
            Configuration-Version:
              description: Configuration file version
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bind'
        '404':
          $ref: '#/components/responses/AlreadyExists'
        default:
          $ref: '#/components/responses/DefaultError'
      summary: Return one bind
      tags:
      - Bind
    put:
      description: Replaces a bind configuration by it's name in the specified frontend.
      operationId: replaceBindLogForward
      parameters:
      - description: Bind name
        in: path
        name: name
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/parent_name'
      - $ref: '#/components/parameters/transaction_id'
      - $ref: '#/components/parameters/version'
      - $ref: '#/components/parameters/force_reload'
      responses:
        '200':
          description: Bind replaced
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bind'
        '202':
          description: Configuration change accepted and reload requested
          headers:
            Reload-ID:
              description: ID of the requested reload
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bind'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/DefaultError'
      summary: Replace a bind
      tags:
      - Bind
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/bind'
        required: true
  /services/haproxy/configuration/peers/{parent_name}/binds/{name}:
    delete:
      description: Deletes a bind configuration by it's name in the specified frontend.
      operationId: deleteBindPeer
      parameters:
      - description: Bind name
        in: path
        name: name
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/parent_name'
      - $ref: '#/components/parameters/transaction_id'
      - $ref: '#/components/parameters/version'
      - $ref: '#/components/parameters/force_reload'
      responses:
        '202':
          description: Configuration change accepted and reload requested
          headers:
            Reload-ID:
              description: ID of the requested reload
              schema:
                type: string
        '204':
          description: Bind deleted
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/DefaultError'
      summary: Delete a bind
      tags:
      - Bind
    get:
      description: Returns one bind configuration by it's name in the specified frontend.
      operationId: getBindPeer
      parameters:
      - description: Bind name
        in: path
        name: name
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/parent_name'
      - $ref: '#/components/parameters/transaction_id'
      responses:
        '200':
          description: Successful operation
          headers:
            Configuration-Version:
              description: Configuration file version
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bind'
        '404':
          $ref: '#/components/responses/AlreadyExists'
        default:
          $ref: '#/components/responses/DefaultError'
      summary: Return one bind
      tags:
      - Bind
    put:
      description: Replaces a bind configuration by it's name in the specified frontend.
      operationId: replaceBindPeer
      parameters:
      - description: Bind name
        in: path
        name: name
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/parent_name'
      - $ref: '#/components/parameters/transaction_id'
      - $ref: '#/components/parameters/version'
      - $ref: '#/components/parameters/force_reload'
      responses:
        '200':
          description: Bind replaced
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bind'
        '202':
          description: Configuration change accepted and reload requested
          headers:
            Reload-ID:
              description: ID of the requested reload
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bind'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/DefaultError'
      summary: Replace a bind
      tags:
      - Bind
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/bind'
        required: true
components:
  parameters:
    transaction_id:
      name: transaction_id
      in: query
      description: ID of the transaction where we want to add the operation. Cannot be used when version is specified.
      required: false
      schema:
        type: string
    version:
      name: version
      in: query
      description: Version used for checking configuration version. Cannot be used when transaction is specified, transaction has it's own version.
      required: false
      schema:
        type: integer
    parent_name:
      name: parent_name
      in: path
      description: Parent name
      required: true
      schema:
        type: string
        pattern: ^[^\r\n<>*;$#&{}"]+$
    force_reload:
      name: force_reload
      in: query
      description: If set, do a force reload, do not wait for the configured reload-delay. Cannot be used when transaction is specified, as changes in transaction are not applied directly to configuration.
      required: false
      schema:
        type: boolean
        default: false
  schemas:
    error:
      additionalProperties:
        type: string
      description: API Error
      properties:
        code:
          type:
          - integer
          - 'null'
        message:
          type:
          - string
          - 'null'
      required:
      - code
      - message
      title: Error
      type: object
    bind:
      allOf:
      - $ref: '#/components/schemas/bind_params'
      - additionalProperties: false
        properties:
          address:
            example: 127.0.0.1
            pattern: ^[^\s]+$
            type: string
          metadata:
            additionalProperties:
              type: object
          name:
            pattern: ^[^\s]+$
            type: string
          port:
            example: 80
            maximum: 65535
            minimum: 1
            type:
            - integer
            - 'null'
          port-range-end:
            example: 81
            maximum: 65535
            minimum: 1
            type:
            - integer
            - 'null'
        required:
        - name
        type: object
      description: HAProxy frontend bind configuration
      title: Bind
    binds:
      title: Binds
      description: HAProxy frontend binds array (corresponds to bind directives)
      type: array
      items:
        $ref: '#/components/schemas/bind'
    bind_params:
      additionalProperties: false
      properties:
        accept_netscaler_cip:
          type: integer
        accept_proxy:
          type: boolean
        allow_0rtt:
          type: boolean
        alpn:
          pattern: ^[^\s]+$
          type: string
          x-display-name: ALPN Protocols
        backlog:
          type: string
        ca_ignore_err:
          type: string
          x-dependency:
            ssl:
              value: true
        ca_sign_file:
          type: string
          x-dependency:
            ssl:
              value: true
        ca_sign_pass:
          type: string
          x-dependency:
            ssl:
              value: true
          x-display-name: Passphrase
        ca_verify_file:
          type: string
          x-dependency:
            ca_file:
              value: true
        cc:
          type: string
          x-display-name: TCP Congestion Control Algorithm
        ciphers:
          type: string
          x-dependency:
            ssl:
              value: true
        ciphersuites:
          type: string
          x-dependency:
            ssl:
              value: true
        client_sigalgs:
          type: string
          x-dependency:
            ssl:
              value: true
        crl_file:
          type: string
          x-dependency:
            ssl:
              value: true
        crt_ignore_err:
          type: string
          x-dependency:
            ssl:
              value: true
        crt_list:
          type: string
          x-dependency:
            ssl:
              value: true
        curves:
          type: string
          x-dependency:
            ssl:
              value: true
        default_crt_list:
          items:
            pattern: ^[^\s]+$
            type: string
          type: array
          x-omitempty: true
        defer_accept:
          type: boolean
        ecdhe:
          type: string
          x-dependency:
            ssl:
              value: true
        expose_fd_listeners:
          type: boolean
        force_sslv3:
          description: This field is deprecated in favor of sslv3, and will be removed in a future release
          type: boolean
          x-deprecated: true
        force_strict_sni:
          enum:
          - enabled
          - disabled
          type: string
          x-dependency:
            ssl:
              value: true
        force_tlsv10:
          description: This field is deprecated in favor of tlsv10, and will be removed in a future release
          type: boolean
          x-deprecated: true
        force_tlsv11:
          description: This field is deprecated in favor of tlsv11, and will be removed in a future release
          type: boolean
          x-deprecated: true
        force_tlsv12:
          description: This field is deprecated in favor of tlsv12, and will be removed in a future release
          type: boolean
          x-deprecated: true
        force_tlsv13:
          description: This field is deprecated in favor of tlsv13, and will be removed in a future release
          type: boolean
          x-deprecated: true
        generate_certificates:
          type: boolean
          x-dependency:
            ssl:
              value: true
        gid:
          type: integer
          x-display-name: Group ID
        group:
          type: string
          x-display-name: Group name
        guid_prefix:
          pattern: ^[A-Za-z0-9-_.:]+$
          type: string
        id:
          type: string
          x-display-name: Socket ID
        idle_ping:
          minimum: 0
          type:
          - integer
          - 'null'
          x-default-unit: ms
          x-duration: true
        interface:
          type: string
        ktls:
          enum:
          - 'on'
          - 'off'
          type: string
          x-display-name: 'Enables or disables ktls for those sockets. If enabled, kTLS will be used if the kernel supports it and the cipher is compatible.

            This is only available on Linux kernel 4.17 and above.

            EXPERIMENTAL OPTION.'
        label:
          type: string
        level:
          enum:
          - user
          - operator
          - admin
          example: user
          type: string
        maxconn:
          example: 1234
          type: integer
        mode:
          type: string
        mss:
          type: string
        namespace:
          example: app
          type: string
        nbconn:
          type: integer
          x-display-name: Number of connection
        nice:
          example: 1
          type: integer
        no_alpn:
          type: boolean
          x-dependency:
            ssl:
              value: true
        no_ca_names:
          type: boolean
          x-dependency:
            ssl:
              value: true
        no_sslv3:
          description: This field is deprecated in favor of sslv3, and will be removed in a future release
          type: boolean
          x-dependency:
            ssl:
              value: true
          x-deprecated: true
        no_strict_sni:
          type: boolean
          x-dependency:
            ssl:
              value: true
          x-deprecated: true
        no_tls_tickets:
          description: This field is deprecated in favor of tls_tickets, and will be removed in a future release
          type: boolean
          x-dependency:
            ssl:
              value: true
          x-deprecated: true
        no_tlsv10:
          description: This field is deprecated in favor of tlsv10, and will be removed in a future release
          type: boolean
          x-dependency:
            ssl:
              value: true
          x-deprecated: true
        no_tlsv11:
          description: This field is deprecated in favor of tlsv11, and will be removed in a future release
          type: boolean
          x-dependency:
            ssl:
              value: true
          x-deprecated: true
        no_tlsv12:
          description: This field is deprecated in favor of tlsv12, and will be removed in a future release
          type: boolean
          x-dependency:
            ssl:
              value: true
          x-deprecated: true
        no_tlsv13:
          description: This field is deprecated in favor of tlsv13, and will be removed in a future release
          type: boolean
          x-dependency:
            ssl:
              value: true
          x-deprecated: true
        npn:
          type: string
        prefer_client_ciphers:
          type: boolean
        proto:
          type: string
          x-display-name: Protocol name
        quic-cc-algo:
          enum:
          - cubic
          - newreno
          - bbr
          - nocc
          type: string
        quic-force-retry:
          type: boolean
        quic-socket:
          enum:
          - connection
          - listener
          type: string
        quic_cc_algo_burst_size:
          maximum: 1024
          minimum: 0
          type:
          - integer
          - 'null'
          x-dependency:
            quic-cc-algo: null
        quic_cc_algo_max_window:
          maximum: 4194304
          minimum: 10
          type:
          - integer
          - 'null'
          x-default-unit: k
          x-dependency:
            quic-cc-algo: null
          x-size: true
        severity_output:
          enum:
          - none
          - number
          - string
          example: none
          type: string
          x-display-name: Format
        shards:
          pattern: ^(by-thread|by-group|[0-9]+)$
          type: string
          x-display-name: Shards
        sigalgs:
          type: string
          x-dependency:
            ssl:
              value: true
        ssl:
          type: boolean
        ssl_cafile:
          pattern: ^[^\s]+$
          type: string
          x-dependency:
            ssl:
              value: true
          x-display-name: SSL CA File
        ssl_certificate:
          description: All of the certificates delimited by ':' as mentioned as a crt on the bind line.
          pattern: ^[^\s]+$
          type: string
          x-dependency:
            ssl:
              value: true
        ssl_max_ver:
          enum:
          - SSLv3
          - TLSv1.0
          - TLSv1.1
          - TLSv1.2
          - TLSv1.3
          type: string
        ssl_min_ver:
          enum:
          - SSLv3
          - TLSv1.0
          - TLSv1.1
          - TLSv1.2
          - TLSv1.3
          type: string
        sslv3:
          enum:
          - enabled
          - disabled
          type: string
          x-dependency:
            ssl:
              value: true
        strict_sni:
          type: boolean
          x-dependency:
            ssl:
              value: true
          x-deprecated: true
        tcp_md5sig:
          pattern: ^[^\s]+$
          type: string
        tcp_ss:
          description: Sets the TCP Save SYN option for all incoming connections instantiated from this listening socket
          enum:
          - 1
          - 2
          - 3
          type: integer
        tcp_user_timeout:
          type:
          - integer
          - 'null'
        tfo:
          type: boolean
        thread:
          type: string
        tls_ticket_keys:
          type: string
        tls_tickets:
          enum:
          - enabled
          - disabled
          type: string
          x-dependency:
            ssl:
              value: true
        tlsv10:
          enum:
          - enabled
          - disabled
          type: string
          x-dependency:
            ssl:
              value: true
        tlsv11:
          enum:
          - enabled
          - disabled
          type: string
          x-dependency:
            ssl:
              value: true
        tlsv12:
          enum:
          - enabled
          - disabled
          type: string
          x-dependency:
            ssl:
              value: true
        tlsv13:
          enum:
          - enabled
          - disabled
          type: string
          x-dependency:
            ssl:
              value: true
        transparent:
          type: boolean
        uid:
          type: string
        user:
          type: string
        v4v6:
          type: boolean
        v6only:
          type: boolean
        verify:
          enum:
          - none
          - optional
          - required
          example: none
          type: string
          x-dependency:
            ssl:
              value: enabled
      type: object
  responses:
    DefaultError:
      description: General Error
      headers:
        Configuration-Version:
          description: Configuration file version
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
    NotFound:
      description: The specified resource was not found
      headers:
        Configuration-Version:
          description: Configuration file version
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
    BadRequest:
      description: Bad request
      headers:
        Configuration-Version:
          description: Configuration file version
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
    AlreadyExists:
      description: The specified resource already exists
      headers:
        Configuration-Version:
          description: Configuration file version
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
  securitySchemes:
    basic_auth:
      type: http
      scheme: basic
externalDocs:
  url: https://docs.haproxy.org/
  description: HAProxy Documentation