spec

---
name: haproxy

description: "The HAProxy server can be used to terminate SSL in front of the Routers. Each HAProxy instance should point to multiple Routers."

packages:
- haproxy
- ttar

templates:
  haproxy_wrapper.erb:          bin/haproxy_wrapper
  reload.erb:                   bin/reload
  drain.erb:                    bin/drain
  pre-start.erb:                bin/pre-start
  bpm.yml:                      config/bpm.yml
  haproxy.config.erb:           config/haproxy.config
  certs.ttar.erb:               config/certs.ttar
  cidrs.ttar.erb:               config/cidrs.ttar
  ssl_redirect.map.erb:         config/ssl_redirect.map
  backend-ca-certs.erb:         config/backend-ca-certs.pem
  client-ca-certs.erb:          config/client-ca-certs.pem
  backend-crt.erb:              config/backend-crt.pem
  client-revocation-list.erb:   config/client-revocation-list.pem
  blacklist_cidrs.txt.erb:      config/blacklist_cidrs.txt
  whitelist_cidrs.txt.erb:      config/whitelist_cidrs.txt
  expect_proxy_cidrs.txt.erb:   config/expect_proxy_cidrs.txt
  trusted_domain_cidrs.txt.erb: config/trusted_domain_cidrs.txt

consumes:
  - name: http_backend
    type: http-router
    optional: true

  - name: tcp_backend
    type: ssh_proxy
    optional: true

  - name: tcp_router
    type: tcp-router
    optional: true

properties:
  ha_proxy.pre_start_script:
    description: |
      This script will be appended to the pre-start script and run before the job starts.
      The pre-start script allows the job to prepare the machine before starting HAProxy,
      for example, by setting the MTU to a custom value.
    default: ~
    example: |
      # customize MTU
      CUST_MTU=((custom_mtu))
      INTERFACE=$(ip -4 route get 8.8.8.8 | grep -Po '(?<=dev )\S+') #'
      CURR_MTU=$(ip link show "$INTERFACE" | grep -Po 'mtu \K\d+')
      if [[ $CURR_MTU -ne $CUST_MTU ]]; then
        sudo ip link set dev "$INTERFACE" mtu "$CUST_MTU"
        echo "MTU changed from $CURR_MTU to $CUST_MTU, interface: $INTERFACE."
      fi
      CURR_MTU=$(ip link show "$INTERFACE" | grep -Po 'mtu \K\d+')
      echo "MTU: $CURR_MTU, interface: $INTERFACE"
  ha_proxy.config_mode:
    description: |
      'auto' - utilizes raw_config if defined and mixes it with raw_blocks; otherwise, it uses traditional configuration mixed with raw_blocks
      'raw_blocks_only' - uses only raw_blocks, ignoring other configurations.
    default: auto
  ha_proxy.nbthread:
    description: "Optional number of threads per VM"
    default: 1
  ha_proxy.syslog_server:
    description: "An IPv4 address optionally followed by a colon and a UDP port. It can also be an IPv6 address or filesystem path to a UNIX domain socket."
    default: "stdout"
  ha_proxy.log_max_length:
    description: "Optional maximum line length. Log lines larger than this value will be truncated before being sent."
    default: 1024
  ha_proxy.log_format:
    description: "The log format used when generating syslog messages."
    default: "raw"
  ha_proxy.log_level:
    description: "Log level"
    default: "info"
  ha_proxy.buffer_size_bytes:
    description: "Buffer size to use for requests, any requests larger than this (large cookies or query strings) will result in a gateway error"
    default: 16384
  ha_proxy.max_rewrite:
    description: "Buffer size to use for header rewriting or appending. The default of haproxy is min(1024,buffer_size_bytes/2). Will be set to buffer_size_bytes/2 by haproxy if it is set to a larger value"
  ha_proxy.internal_only_domains:
    description: "Array of domains for internal-only apps/services (not hostnames for the apps/services)"
    default: []
  ha_proxy.trusted_domain_cidrs:
    description: "Space separated trusted cidr blocks for internal_only_domains. You may alternatively provide a base64-encoded gzipped HAProxy cidr file, with each CIDR on a new line."
    default: 0.0.0.0/32
  ha_proxy.strict_sni:
    description: "Optional setting to decide whether the SSL/TLS negotiation is allowed only if the client provided an SNI which strict match a certificate. If set to true, the default certificate is not used"
    default: false
  ha_proxy.disable_domain_fronting:
    description: |
      Must be one of true, false, or "mtls_only"
      If set to true, it will prevent clients from setting a host header different from the SNI value for HTTPS and WSS (secured websockets) connections. This is called domain fronting and is mostly used by CDNs.
      If domain fronting is disabled, such requests will result in a 421 Misdirected Request error.
      If set to "mtls_only", the host header will only be checked against the SNI for mtls connections
      Example
        curl -H "Host: bob.com" https://alice.com    <-- This will result in a 421 Misdirected Request
    default: false
  ha_proxy.ssl_pem:
    description: |
      Array of private keys and certificates used for TLS handshakes with downstream clients. Each element in the array is an object containing fields 'cert_chain' and 'private_key',
      each of which supports a PEM block. Each element can also be a single string containing the cert chain and the private key.
    example:
      ssl_pem:
      - cert_chain: |
          -----BEGIN CERTIFICATE-----
          -----END CERTIFICATE-----
          -----BEGIN CERTIFICATE-----
          -----END CERTIFICATE-----
        private_key: |
          -----BEGIN RSA PRIVATE KEY-----
          -----END RSA PRIVATE KEY-----
      - |
        -----BEGIN CERTIFICATE-----
        -----END CERTIFICATE-----
        -----BEGIN CERTIFICATE-----
        -----END CERTIFICATE-----
        -----BEGIN RSA PRIVATE KEY-----
        -----END RSA PRIVATE KEY-----
    default: ~
  ha_proxy.crt_list:
    description: |
      Array of private keys and certificates used for TLS handshakes with downstream clients. Each element in the array is an object containing at least the field 'ssl_pem'.
      The field 'ssl_pem' itself is either an object containing fields 'cert_chain' and 'private_key', or a single string containing the cert chain and the private key.
      The following fields are optional:
      - 'alpn' (a optional array of strings). If both HTTP/2 and HTTP/1.1 are expected to be supported, both versions can be advertised, in order of preference
      - 'client_ca_file' (replaces ha_proxy.client_ca_file)
      - 'verify' (allowed values: [none|optional|required])
      - 'ssl_ciphers' (overrides ha_proxy.ssl_ciphers)
      - 'ssl_ciphersuites' (overrides ha_proxy.ssl_ciphersuites)
      - 'ssl_min_version' (allowed values: [SSLv3 | TLSv1.0 | TLSv1.1 | TLSv1.2 | TLSv1.3])
      - 'ssl_max_version' (allowed values: [SSLv3 | TLSv1.0 | TLSv1.1 | TLSv1.2 | TLSv1.3])
      - 'client_revocation_list' (replaces ha_proxy.client_revocation_list)
      - 'snifilter' (either a string or an array of strings)
      The global option ha_proxy.client_cert has to be set to 'true', if there are crt_list entries with mutual auth configuration ('client_ca_file', 'client_revocation_list' and 'verify'!='none')
      To avoid confusing configurations, it's not allowed to specify 'client_ca_file' and 'client_revocation_list' both globally AND in crt_list entries.
    example:
      crt_list:
      - ssl_pem: |
          -----BEGIN CERTIFICATE-----
          -----END CERTIFICATE-----
          -----BEGIN CERTIFICATE-----
          -----END CERTIFICATE-----
          -----BEGIN RSA PRIVATE KEY-----
          -----END RSA PRIVATE KEY-----
      - ssl_pem:
          cert_chain: |
            -----BEGIN CERTIFICATE-----
            -----END CERTIFICATE-----
            -----BEGIN CERTIFICATE-----
            -----END CERTIFICATE-----
          private_key: |
            -----BEGIN RSA PRIVATE KEY-----
            -----END RSA PRIVATE KEY-----
        client_ca_file: |
          -----BEGIN CERTIFICATE-----
          -----END CERTIFICATE-----
          -----BEGIN CERTIFICATE-----
          -----END CERTIFICATE-----
        verify: required
        ssl_ciphers: AES:ALL:!aNULL:!eNULL:+RC4:@STRENGTH
        ssl_ciphersuites: TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256
        ssl_min_version: TLSv1.2
        ssl_max_version: TLSv1.3
        alpn:
        - h2
        - http/1.1
        client_revocation_list: |
          -----BEGIN X509 CRL-----
          -----END X509 CRL-----
          -----BEGIN X509 CRL-----
          -----END X509 CRL-----
        snifilter:
        - "*.domain.tld"
        - "!secure.domain.tld"
    default: ~
  ha_proxy.ext_crt_list:
    description: |
      A flag denoting the use of additional certificates from external sources.
      If set to true the contents of an external crt-list file located at `ha_proxy.ext_crt_list_file` are
      added to the crt-list described by the `ha_proxy.crt_list` property. Please be aware that reloading external certificates does only work if haproxy is
      started in daemon mode. So this feature does not work if "haproxy.syslog_server" is set to "stdout". If using this feature but not using internal certs,
      you should set ha_proxy.crt_list to be an empty array
    default: false
  ha_proxy.ext_crt_list_file:
    description: |
      The location from which to load additional external certificates list
    default: "/var/vcap/jobs/haproxy/config/ssl/ext/crt-list"
  ha_proxy.ext_crt_list_timeout:
    description: |
      Timeout (in seconds) to wait for the external certificates list located at `ha_proxy.ext_crt_list_file` to appear during HAproxy startup
    default: 60
  ha_proxy.ext_crt_list_policy:
    description: |
      What to do if the external certificates list located at `ha_proxy.ext_crt_list_file` does not appear within the time
      denoted by `ha_proxy.ext_crt_list_timeout`. Set to either 'fail' (HAproxy will not start) or 'continue' (HAproxy will start without external certificates)
    default: "fail"
  ha_proxy.reload_idle_close_on_response:
    description: |
      This option makes HAproxy wait for another request on idle connections during reloads or restarts. Once the response is received, a "Connection: close" header
      is injected to signal to the client that this connection no longer usable and permitting a more graceful handling on the client's side. This has the downside
      that HAproxy may linger around for longer, waiting for a request on idle connections, so it should be used in conjunction with the "reload_hard_stop_after" option
      to limit that time. If set to false, idle connections will be terminated immediately during reloads or restarts.
    default: true
  ha_proxy.reload_hard_stop_after:
    description: |
      Defines the maximum time allowed to perform a clean soft-stop. This is used when issuing a reload via the "bin/reload" script. It limits the time for the
      old instance to finish existing connections before the instance is stopped.
    default: "5m"
  ha_proxy.reload_max_instances:
    description: |
      Sets the maximum number of instances to exist at the same time. In conjunction with "reload_hard_stop_after" this limits the number of reloads that can occur
      during a given period of time. Set this to the number of instances your machine can fit into memory at a time, minus a safety buffer. Set to 0 for no limit.
    default: 4
  ha_proxy.backend_ca_file:
    description: "Optional SSL CA certificate chain (PEM file) concatenated together for backend SSL servers, only used when one of the `backend_ssl` options is set to `verify`"
  ha_proxy.enable_health_check_http:
    description: "Optionally enable http health-check on `haproxy_ip:8080/health`. It shows `200 OK` if >0 backend servers are up. If used with ext_crt_list_timeout you should make sure that the deployment canary_watch_time and update_watch_time are configured to wait at least the number of seconds defined by ext_crt_list_timeout."
    default: false
  ha_proxy.disable_monit_health_check_http:
    description: "The HAProxy health check endpoint returns a healthy status if at least one backend server is responding. By default when enable_health_check_http: true, Bosh will consider the HAProxy VM unhealthy if the HAProxy health check returns an unhealthy status. In some cases this might not be desired, for example when deploying HAProxy before deploying the backend servers. To prevent Bosh from considering the HAProxy VM unhealthy when all backend servers are unhealthy set disable_monit_health_check_http: true. Note that this flag is ignored unless enable_health_check_http: true."
    default: false
  ha_proxy.health_check_port:
    description: "port for http health-check. Please note that `health_check_port` + 1 (e.g. 8081) is used with the `accept-proxy` directive, if `expect_proxy_cidrs` are defined. You will need to direct your health checker to the appropriate port (with or without Proxy Protocol) for correct functionality."
    default: 8080
  ha_proxy.disable_http:
    description: "Disable port 80 traffic"
    default: false
  ha_proxy.enable_4443:
    description: "Enables port 4443 for backwards compatibility with WSS-based apps using the old CF haproxy. If true you must provide a valid SSL config via ssl_pem or crt_list"
    default: false
  ha_proxy.https_redirect_domains:
    description: "For each domain in this array, a HTTPS redirect rule will be put in the config file. Redirect will be applied for all subdomains"
    default: []
  ha_proxy.https_redirect_all:
    description: "If this is set to 'true', a https redirect rule for all http calls will be put in the config file"
    default: false
  ha_proxy.ssl_ciphers:
    default: ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA256:DHE-RSA-AES256-SHA:ECDHE-ECDSA-DES-CBC3-SHA:ECDHE-RSA-DES-CBC3-SHA:EDH-RSA-DES-CBC3-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:DES-CBC3-SHA:!DSS
    description: "List of TLSv<=1.2 Ciphers for that are passed to HAProxy"
  ha_proxy.ssl_ciphersuites:
    example: TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256
    description: "List of TLSv1.3 Ciphers that are passed to HAProxy, requires at least openssl version 1.1.1"
  ha_proxy.hsts_enable:
    default: false
    description: "Enables HSTS(Strict-Transport-Security Header) for all the SSL/TLS listeners"
  ha_proxy.hsts_max_age:
    default: 31536000
    description: "max-age value for the Strict-Transport-Security header"
  ha_proxy.hsts_include_subdomains:
    default: false
    description: "This enables the includeSubDomains flag for HSTS."
  ha_proxy.hsts_preload:
    default: false
    description: "This enables the preload flag for HSTS"
  ha_proxy.default_dh_param:
    default: 2048
    description: "Maximum size of DH params when generating ephemeral keys during key exchange"
  ha_proxy.disable_tls_tickets:
    default: true
    description: "Improve (Perfect) Forward Secrecy by disabling TLS tickets."
  ha_proxy.ssl_min_ver:
    example: "TLSv1.2"
    description: |
      This option enforces the use of 'version' or higher for SSL connections initiated from this listener.
      The recommended value is 'TLSv1.2'. It is not the default due to backward compatibility concerns with
      the 'disable_tls_*' options. If this option is set, the 'disable_tls_1*' options will be ignored.
  ha_proxy.ssl_max_ver:
    example: "TLSv1.3"
    description: |
      This option enforces the use of 'version' or lower for SSL connections initiated from this listener.
      It will only be set if 'ssl_min_ver' is specified, as the default HAProxy ssl-min-ver may change in future.
  ha_proxy.disable_tls_10:
    default: false
    description: "Disable TLS 1.0 in HA Proxy. Use 'ssl_min_ver' and 'ssl_max_ver' instead."
  ha_proxy.disable_tls_11:
    default: false
    description: "Disable TLS 1.1 in HA Proxy. Use 'ssl_min_ver' and 'ssl_max_ver' instead."
  ha_proxy.disable_tls_12:
    default: false
    description: "Disable TLS 1.2 in HA Proxy. Use 'ssl_min_ver' and 'ssl_max_ver' instead."
  ha_proxy.disable_tls_13:
    default: false
    description: "Disable TLS 1.3 in HA Proxy. Use 'ssl_min_ver' and 'ssl_max_ver' instead."
  ha_proxy.backend_match_http_protocol:
    default: false
    description: Uses the same version of HTTP for backend connections that was used for frontend connections (ie HTTP 1.1 or HTTP 2). Ignores the value of enable_http2. HTTP2 backend connections require that `ha_proxy.backend_ssl` is not `off`.
  ha_proxy.disable_backend_http2_websockets:
    default: false
    description: "Forward websockets to the backend servers using HTTP/1.1, never HTTP/2. Does not apply to custom routed_backend_servers. Works around https://github.com/cloudfoundry/routing-release/issues/230. Overrides backend_match_http_protocol for websockets."
  ha_proxy.enable_redispatch:
    default: false
    description: "When enabled, HAProxy will try to connect to another server if a connect attempt fails. Best used in conjunction with retries."
  ha_proxy.retries:
    default: 0
    description: "HAProxy will retry this many times on failed connections. When redispatch is enabled, the retries may occur on different servers. In combination with connect_timeout this defines the maximum response time of HAProxy to clients. e.g. 0.5s connect_timeout * 10 retries = 5s max response time"

  ha_proxy.connect_timeout:
    description: "Timeout (in floating point seconds) used on connections from haproxy to a backend, while waiting for the TCP handshake to complete + connection to establish"
    default:     5
  ha_proxy.client_timeout:
    description: "Timeout (in floating point seconds) used on connections from a client to haproxy that have gone inactive"
    default:     30
  ha_proxy.server_timeout:
    description: "Timeout (in floating point seconds) used on connections from haproxy to a backend, while waiting for data from the backend"
    default:     30
  ha_proxy.websocket_timeout:
    description: "Timeout (in floating point seconds) used on websocket/tunnel traffic, when both ends of the conversation have become inactive"
    default:     3600
  ha_proxy.keepalive_timeout:
    description: "Timeout (in floating point seconds) applied to any connection that is in an http-keepalive state, waiting for the next request to occur"
    default:     6
  ha_proxy.request_timeout:
    description: "Timeout (in floating point seconds) applied to any connection to limit the maximum time for a complete HTTP request (headers only). Used to limit DoS attacks that send data slowly to not trigger the client/server timeouts"
    default:     5
  ha_proxy.queue_timeout:
    description: "Timeout (in floating point seconds) used on any connection sitting in the pending queue, waiting to be sent to the backend, to limit its time being queued"
    default:     30

  ha_proxy.stats_enable:
    description: "If true, haproxy will enable a socket for stats. You can see the stats on `haproxy_ip:9000/haproxy_stats`. If multithreading is enabled (`ha_proxy.threads > 1`) haproxy will create a separate socket and stat page for each thread. Each stat page is reachable on a different port ranging from `9000` to `9000 + ha_proxy.threads - 1`."
    default: false
  ha_proxy.stats_bind:
    description: "Define listening address and port for the stats frontend. If multithreading is enabled (`ha_proxy.threads > 1`) multiple stat pages are available - one for each thread. You can see the stat page for each thread on a separate port - starting at the defined port number."
    default: "*:9000"
  ha_proxy.stats_user:
    description: "User name to authenticate haproxy stats, leave empty if you want the statistics to be available without authentication"
  ha_proxy.stats_password:
    description: "Password to authenticate haproxy stats, ignored when 'stats_user' is empty"
  ha_proxy.stats_uri:
    description: "URI used to access the stats UI."
    default: "haproxy_stats"
  ha_proxy.trusted_stats_cidrs:
    description: "Trusted ip range that can access the stats UI"
    default: 0.0.0.0/32
  ha_proxy.stats_promex_enable:
     description: "If true, haproxy will enable native prometheus exporter."
     default: false
  ha_proxy.stats_promex_path:
    description: "Define prometheus exporter path."
    default: "/metrics"

  ha_proxy.master_cli_enable:
    description: "If true, enables the master CLI which can be used to manage HAProxy"
    default: false
  ha_proxy.master_cli_bind:
    description: "IP and port or UNIX socket to bind master CLI to"
    default: "127.0.0.1:9001"

  ha_proxy.backend_servers:
    description: "Array of the router IPs acting as the HTTP/TCP backends (should include servers all Availability Zones being used)"
    default: []
  ha_proxy.backend_ssl:
    description: "Optionally enable SSL verification for backend servers, one of `verify`, `noverify`, any other value assumes no ssl backend.  Setting `verify` requires `ha_proxy.backend_ca_file` key to be set. Note that `off` will disable all backend HTTP2 support regardless of other properties."
    default: "off"
  ha_proxy.backend_ssl_verifyhost:
    description: "Optional hostname to verify in the x509 certificate subject for SSL-enabled backend servers.  Requires `ha_proxy.backend_ssl` is set to `verify` when using this."
  ha_proxy.backend_port:
    description: "Listening port for Router"
    default: 80
  ha_proxy.compress_types:
    description: "If this property is set, gzip compression will be activated for the mime types named in this property. definition like 'text/html text/plain text/css'"
    default: ""
  ha_proxy.routed_backend_servers:
    description: "Hash of the URL prefixes -> array of the router IPs acting as the HTTP/TCP backends (should include servers all Availability Zones being used)"
    default: {}
    example:
      routed_backend_servers:
        /images:
          servers: [10.0.0.2, 10.0.0.3]  # required - list of backend IPs to connect to
          port: 4443       # required - port haproxy should listen on
          backend_ssl: "verify"  # optional - enables ssl backend, one of `verify`, `noverify`, any other value assumes no ssl backend.
                                 # Setting `verify` requires `ha_proxy.backend_ca_file` key to be set.
          backend_verifyhost: example.com # optional - hostname to verify in the x509 certificate subject for SSL-enabled backend servers
                                          # only used if backend_ssl: `verify` is set
          backend_use_http_health:  true    # optional, defaults to false. enables http based health checks for the backend
          backend_http_health_port: 80      # optional, defaults to the port of the backend server. sets the port for the http backend health check
          backend_http_health_uri:  /health # optional, defaults to /health. sets the URI for backend http health checks
          backend_health_fall: 3  # optional, ignored if backend_use_http_health is false. Defaults to 3 if not set. Number of consecutive unsuccessful health checks required before the server is considered unhealthy from a healthy state.
          backend_health_rise: 2  # optional, ignored if backend_use_http_health is false. Defaults to 2 if not set. Number of consecutive successful health checks required before the server is considered healthy from an unhealthy state.
          additional_acls: ["method GET"] # optional, defaults to []. Include additional ACLs that are required for this backend to be used. ACLs are combined with logical AND

  ha_proxy.strip_headers:
    description: "List of custom headers to delete on each request. Spaces are automatically escaped, but any other haproxy delimiters will need to be escaped manually"
    example: |
      strip_headers:
        - MyHeader
        - MyCustomHeaderToDelete

  ha_proxy.headers:
    description: "Hash of custom headers you wish you have set on each request. Spaces are automatically escaped, but any other haproxy delimiters will need to be escaped manually"
    example: |
      headers:
        X-Application-ID: my-custom-header
        MyCustomHeader: 3

  ha_proxy.rsp_headers:
    description: "Hash of custom headers you wish you have set on each request. Spaces are automatically escaped, but any other haproxy delimiters will need to be escaped manually"
    example: |
      rsp_headers:
        X-Application-ID: my-custom-header
        MyCustomHeader: 3

  ha_proxy.true_client_ip_header:
    description: "Header to use to store the client's IP address, as seen from HAProxy. See forward_true_client_ip_header for more options."

  ha_proxy.forward_true_client_ip_header:
    description: |
      This option lets you decide how to handle the header specified in ha_proxy.true_client_ip_header on any http and https frontend, when it already present in the request.
      Your options are:
      
      - always_forward: Always preserve the existing header.
      
      - forward_only_if_route_service: This option is useful to support the header with Route Services.
          The header will be overwritten with the current source address, unless there is an X-Cf-Proxy-Signature header.
      
      - always_set: Always set the header with the current source address. Will overwrite any existing header.

    default: forward_only_if_route_service

  ha_proxy.backend_crt:
    description: "Provides client certificate to backend server to do mutual ssl. Note this only configures the client cert for HTTP backends configured via the backend_servers property or through BOSH links. It is not used with backend servers configured via routed_backend_servers or TCP backends"
    example: |
      -----BEGIN CERTIFICATE-----
      ******
      -----END CERTIFICATE-----
      -----BEGIN PRIVATE KEY-----
      ******
      -----END PRIVATE KEY-----
  ha_proxy.client_cert:
    description: |
      Enable haproxy mutual auth
    default: false

  ha_proxy.forwarded_client_cert:
    description: |
      This option lets you decide how to handle the X-Forwarded-Client-Cert (XFCC) http header on any https frontend.
      On http frontends the `always_forward_only` option is active by default and can't be changed.
      On https frontends your options are:

      - always_forward_only: Least secure option. Always forward the X-Forwarded-Client-Cert header in the request, regardless of whether the client connection is mTLS. The following headers will also be forwarded if they are present in the original request: X-SSL-Client, X-SSL-Client-Session-ID, X-SSL-Client-Verify, X-SSL-Client-Subject-DN, X-SSL-Client-Subject-CN, X-SSL-Client-Issuer-DN, X-SSL-Client-NotBefore, X-SSL-Client-NotAfter.
          Use this value when your load balancer is forwarding the client certificate and requests are not forwarded to HAProxy over mTLS.
          In the case where the connection between load balancer and HAProxy is mTLS, the client certificate received by HAProxy in the mTLS handshake will not be forwarded.

      - forward_only: Secure version of `always_forward_only`. Forward the X-Forwarded-Client-Cert header received from the client only when the client connection is mTLS. The following headers will also be forwarded for mTLS connections if they are present in the original request: X-SSL-Client, X-SSL-Client-Session-ID, X-SSL-Client-Verify, X-SSL-Client-Subject-DN, X-SSL-Client-Subject-CN, X-SSL-Client-Issuer-DN, X-SSL-Client-NotBefore, X-SSL-Client-NotAfter.
          If the client connection does not use mTLS, these X-Forwarded-Client-Cert and X-SSL-Client-* headers will be removed if they are present.
          In the case where the connection between load balancer and HAProxy is mTLS, the client certificate received by HAProxy in the mTLS handshake will not be forwarded.

      - sanitize_set: Most secure option. Strip any instances of XFCC headers from the client request.

          When the client connection is mTLS, the following headers will be overwritten in the request

            - X-Forwarded-Client-Cert: Contains the client certificate in binary DER format (Base64 encoded). Backends should use this header to authenticate incoming requests.

            - X-SSL-Client: Contains the number 1 if the request was made using a client certificate, 0 otherwise. For easy checks on the backend.

            - X-SSL-Client-Session-ID: The SSL session ID of the client connection. Useful for debugging purposes.

            - X-SSL-Client-Verify: Contains the number 0 if the client certificate verification was successful. Otherwise it contains the appropriate OpenSSL return code (see https://github.com/openssl/openssl/blob/master/include/openssl/x509_vfy.h.in#L206)

            - X-SSL-Client-Subject-DN: Contains the base64-encoded subject distinguished name of the client certificate

            - X-SSL-Client-Subject-CN: Contains the base64-encoded subject common name of the client certificate

            - X-SSL-Client-Issuer-DN: Contains the base64-encoded issuer distinguished name of the client certificate

            - X-SSL-Client-Root-CA-DN: X-SSL-Client-Root-CA-DN: Contains base64-encoded subject DN of the root CA which signed the client certificate

            - X-SSL-Client-NotBefore: Contains the start date of the client certificate in YYMMDDhhmmss[Z] format.

            - X-SSL-Client-NotAfter: Contains the expiration date of the client certificate in YYMMDDhhmmss[Z] format.

      - forward_only_if_route_service:
          This option is useful to support Mutual TLS with CF Route Services.
          When the client connection is not mTLS, the X-Forwarded-Client-Cert and X-SSL-Client-* headers will be removed UNLESS there is an X-Cf-Proxy-Signature header.
          When the client connection is mTLS, the following headers will be overwritten in the request

            - X-Forwarded-Client-Cert: Contains the client certificate in binary DER format (Base64 encoded). Backends should use this header to authenticate incoming requests.

            - X-SSL-Client: Contains the number 1 if the request was made using a client certificate, 0 otherwise. For easy checks on the backend.

            - X-SSL-Client-Session-ID: The SSL session ID of the client connection. Useful for debugging purposes.

            - X-SSL-Client-Verify: Contains the number 0 if the client certificate verification was successful. Otherwise it contains the appropriate OpenSSL return code (see https://github.com/openssl/openssl/blob/master/include/openssl/x509_vfy.h.in#L206)

            - X-SSL-Client-Subject-DN: Contains the base64-encoded subject distinguished name of the client certificate

            - X-SSL-Client-Subject-CN: Contains the base64-encoded subject common name of the client certificate

            - X-SSL-Client-Issuer-DN: Contains the base64-encoded issuer distinguished name of the client certificate

            - X-SSL-Client-NotBefore: Contains the start date of the client certificate in YYMMDDhhmmss[Z] format.

            - X-SSL-Client-NotAfter: Contains the expiration date of the client certificate in YYMMDDhhmmss[Z] format.

          This option is only secure if Gorouter is deployed behind Haproxy to validate that X-Cf-Proxy-Signature is coming from a route service.
    default: sanitize_set

  ha_proxy.legacy_xfcc_header_mapping:
    default: false

  ha_proxy.client_ca_file:
    description: "path for CA certs to validate client certificate"
    example: |
      -----BEGIN CERTIFICATE-----
      ******
      -----END CERTIFICATE-----
      -----BEGIN PRIVATE KEY-----
      ******
      -----END PRIVATE KEY-----

  ha_proxy.client_cert_ignore_err:
    description: |
      Error code(s) to ignore from verifying a client cert during a mutual ssl handshake, in a comma-separated list.
      For example, 2 is if it cannot get the issuer certificate, 10 if the certificate has expired and 18 if the certificate is self-signed.
      The keyword 'all' will ignore all possible errors.
      Note that the errors will be ignored on both the certificate and the CA verification.
      See the openssl verify documentation [https://www.openssl.org/docs/manmaster/man3/X509_STORE_CTX_get_error.html] for a full list of all error codes and their meanings.
      See https://github.com/openssl/openssl/blob/master/include/openssl/x509_vfy.h.in#L206 for a mapping of error codes to symbols.
    example: 2,10,18

  ha_proxy.client_revocation_list:
    description: "provide a list of revocation certs"

  ha_proxy.tcp:
    description: "List of mappings to perform tcp-based proxying on. See example for mapping datastructure and keys"
    default: []
    example:
      tcp:
        - name: wss        # required - name of backend
          port: 4443       # required - port haproxy should listen on
          backend_servers: # required - list of backend IPs to connect to
          - 10.20.10.10
          - 10.20.10.11
          backend_servers_local: # optional - list of backend IPs which have priority routing (for example those in the same AZ). IPs must also be included in backend_servers.
          - 10.20.10.10
          balance: roundrobin # optional - sets algorithm used to select a server when doing load balancing
          backend_port: 80 # optional - sets backend port - otherwise defaults to `port`
          ssl: true        # optional - enables ssl, and uses the `ha_proxy.ssl_pem` provided key
          backend_ssl: "verify"  # optional - enables ssl backend, one of `verify`, `noverify`, any other value assumes no ssl backend.
                                 # Setting `verify` requires `ha_proxy.backend_ca_file` key to be set.
          backend_verifyhost: example.com # optional - hostname to verify in the x509 certificate subject for SSL-enabled backend servers
                                          # only used if backend_ssl: `verify` is set
          health_check_http: 4444 # optional port number - if provided a heath check http site is created at `haproxy_ip:4444/health`.
                                  # It shows `200 OK` if >0 backend servers are up.
  ha_proxy.tcp_link_port:
    description: "Port haproxy should listen on when using the tcp_backend link"
  ha_proxy.tcp_link_check_port:
    description: "Optional port for tcp_backend health checks. Will use ha_proxy.tcp_link_port if not set."
  ha_proxy.tcp_link_health_check_http:
    description: "Optional port for http health check when using the tcp_backend link."
  ha_proxy.resolvers:
    description: "List of DNS servers"
    example:
      resolvers:
      - private: 10.0.0.2
      - public: 8.8.8.8
  ha_proxy.dns_hold:
    description: "DNS Hold time"
    default: 10s
  ha_proxy.resolve_retry_timeout:
    description: "Timeouts related to resolver name resolution"
    default: 1s
  ha_proxy.resolve_retries:
    description: "Number of dns queries to send to resolve a server name before giving up"
    default: 3
  ha_proxy.accept_proxy:
    description: "Turned off by default. Enforces the use of the PROXY protocol for all incoming connections to all frontends, with the exception of local requests to the health check endpoint, since Monit does not support PROXY protocol. When enabled, standard TCP connections to these ports no longer work."
    default: false
  ha_proxy.disable_tcp_accept_proxy:
    description: "Disables the PROXY protocol on tcp backends. Only applies if `ha_proxy.accept_proxy` is enabled."
    default: false
  ha_proxy.disable_health_check_proxy:
    description: "Disables the use of the PROXY protocol for health checks. Only applies if `ha_proxy.accept_proxy` is enabled."
    default: false
  ha_proxy.enable_additional_health_check_proxy:
      description: "Enable the additional health check listener with use of the PROXY protocol"
      default: false
  ha_proxy.binding_ip:
    description: "If there are multiple ethernet interfaces, specify which one to bind. Set to `::` to bind to all IPv6 interfaces (no IPv4). IPv6 must be enabled on the HAProxy VM in the deployment manifest."
    default: ""
  ha_proxy.v4v6:
    description: "Boolean, disabled by default. Enables binding to all IPv4 and IPv6 interfaces. Only applies if `ha_proxy.binding_ip` is set to `::`."
    default: false

  ha_proxy.cidr_blacklist:
    description: "List of CIDRs to block for http(s). Format is string array of CIDRs or single string of base64 encoded gzip."
    default: ~
    example:
      cidr_blacklist:
      - 10.0.0.0/8
      - 192.168.2.0/24
  ha_proxy.cidr_whitelist:
    description: "List of CIDRs to allow for http(s). Format is string array of CIDRs or single string of base64 encoded gzip. Note that unless ha_proxy.block_all is true, non-whitelisted traffic will still be allowed, provided that traffic is not also blacklisted"
    default: ~
    example:
      cidr_whitelist:
      - 172.168.4.1/32
      - 10.2.0.0/16
  ha_proxy.expect_proxy_cidrs:
    description: "List of CIDRs to enable proxy protocol for. This enables forwarding of the client source IP for hyperscalers not supporting IP dual stack (v4 & v6). This property is mutually exclusive with the accept_proxy."
    default: ~
    example:
      expect_proxy_cidrs:
      - 10.6.7.8/27
      - 2001:db8::/32
  ha_proxy.block_all:
    description: "Optionally block all incoming traffic to http(s). Use in conjunction with whitelist."
    default: false

  ha_proxy.tcp_routing.port_range:
    description: "A range of ports for haproxy to listen on to enable CF TCP Routing. Used only if 'tcp_router' link is present."
    default: 1024-1123

  ha_proxy.http_request_deny_conditions:
      description: |
        List of conditions to block http requests. Each condition consists of multiple rules combined with the AND operator. Setting
        the negate flag to true will negate the acl condition.

      example:
        http_request_deny_conditions:
        - condition:
          - acl_name: block_host
            acl_rule: "hdr_beg(host) -i login"
          - acl_name: block_reset_password_url
            acl_rule: "path_beg,url_dec -m beg -i /reset_password"
          - acl_name: whitelist_ips
            acl_rule: "src 5.22.5.11 5.22.5.12"
            negate: true


  ha_proxy.cidrs_in_file:
    description: |
      List of cidrs that will be placed in /var/vcap/jobs/haproxy/config/cidrs/<name>. Useful for acl's that reference
      a long list of cidrs (invoke the file with -f /var/vcap/jobs/haproxy/config/cidrs/<name>).

    example:
      cidrs_in_file:
      - name: sample_cidrs
        cidrs:
        - 5.22.1.3
        - 5.22.12.3

  ha_proxy.lua_scripts:
    description: |
      A list of LUA scripts that HA Proxy should load. These will need to be provided
      by other boshreleases, as none are supplied in `haproxy_boshrelease`. Specify
      each script with the full path to the script (likely `/var/vcap/packages/something/something/darkside.lua`)

      Inside these scripts, any variable set is visible
      from any thread. This is the easiest and recommended way to load Lua programs
      but it will not scale well if a lot of Lua calls are performed, as only one
      thread may be running on the global state at a time. A program loaded this
      way will always see 0 in the "core.thread" variable. This directive can be
      used multiple times.

    default: []

  ha_proxy.lua_scripts_per_thread:
    description: |
      A list of LUA scripts that HA Proxy should load per thread. These will need to be provided
      by other boshreleases, as none are supplied in `haproxy_boshrelease`. Specify
      each script with the full path to the script (likely `/var/vcap/packages/something/something/darkside.lua`).

      Inside these scripts, any global variable has a thread-local visibility so that each thread could
      see a different value. As such it is strongly recommended not to use global
      variables in programs loaded this way. An independent copy is loaded and
      initialized for each thread, everything is done sequentially and in the
      thread's numeric order from 1 to nbthread. If some operations need to be
      performed only once, the program should check the "core.thread" variable to
      figure what thread is being initialized. Programs loaded this way will run
      concurrently on all threads and will be highly scalable. This is the
      recommended way to load simple functions that register sample-fetches,
      converters, actions or services once it is certain the program doesn't depend
      on global variables. For the sake of simplicity, the directive is available
      even if only one thread is used and even if threads are disabled (in which
      case it will be equivalent to `lua_scripts`).

    default: []

  ha_proxy.additional_unrestricted_volumes:
    description: |
      Map of Additional Unrestricted volumes to added so HA Proxy to give the ability to load external volumes under BPM. These will need to be provided
      in a Map based on bpm unrestricted volume spec
    default: ~


  ha_proxy.backend_use_http_health:
    description: |
      Enables HTTP based health checks for the default backend
    default: false
  ha_proxy.backend_http_health_uri:
    description: URI to request when checking the health of a backend
    default: /health
  ha_proxy.backend_http_health_port:
    description: Port to check the backend health on
    default: 8080
  ha_proxy.backend_health_fall:
    description: Number of consecutive unsuccessful health checks required before the server is considered unhealthy from a healthy state. The default value of 3 matches the default if the parameter is undefined. This parameter will be ignored if ha_proxy.backend_use_http_health is false.
    default: 3
  ha_proxy.backend_health_rise:
    description: Number of consecutive successful health checks required before the server is considered healthy from an unhealthy state. The default value of 2 matches the default if the parameter is undefined. This parameter will be ignored if ha_proxy.backend_use_http_health is false.
    default: 2
  ha_proxy.backend_https_check:
    description: Set to true if the backend uses TLS on the health endpoint. Adds the check-ssl option to the backend configs. If backend certificate on traffic port is verified the Health endpoint cert will also be verified.  
    default: false
    
  ha_proxy.global_config:
    description: |
      Raw HAProxy config that will be added to the HA proxy global section, provided either as a multiline text blob or as an array of lines.

  ha_proxy.default_config:
    description: |
      Raw HAProxy config that will be added to the HA proxy default section, provided either as a multiline text blob or as an array of lines.

  ha_proxy.frontend_config:
    description: |
      Raw HAProxy config that will be added to each HA proxy frontend definition, provided either as a multiline text blob or as an array of lines.

  ha_proxy.backend_config:
    description: |
      Raw HAProxy config that will be added to the default HTTP + routed HTTP backend definitions, provided either as a multiline text blob or as an array of lines.
  ha_proxy.backend_config_targeted:
    description: |
      A map of existing backends which enables more fine-grained configuration of the backend.
      example:
        backend_config_targeted:
          http-routers-http1: |
            http-reuse aggressive
          http-routers-http2: |
            http-reuse safe
  ha_proxy.custom_http_error_files:
    description: |
      A map of status codes to errorfile contents
    default:
      "503": |
               HTTP/1.1 503 Service Unavailable
               Cache-Control: no-cache
               Connection: close
               Content-Type: text/html

               <html><body><h1>503 Service Unavailable</h1>
               No server is available to handle this request.
               </body></html>
  ha_proxy.tcp_backend_config:
    description: |
      Raw HAProxy config that will be added to the CF TCP Router + Generic TCP backend definitions, provided either as a multiline text blob or as an array of lines.

  ha_proxy.raw_config:
    description: |
      A multiline text blob of an entire haproxy config. Overrides every other
      option available, so you can provide your own config, and do whatever
      you want. Use at your own risk.
  ha_proxy.raw_blocks:
    description: |
      A hash of block types, where each type contains either a configuration
      or a hash of specific block names with their respective configurations.
      The configurations are provided as either multiline text blobs or arrays of lines.
      This structure will be appended to the end of the HAProxy configuration file.
      Use at your own risk.
    example:
      defaults: |
        log global
        timeout http-request 10s
      listen:
        my-listen-x: |
          bind :81
          mode http
          server-template srv 1-3 q-s0.web.default.deployment-x.bosh:8080 check inter 1000
        my-listen-y:
          - bind :82
          - mode http
          - server-template srv 1-3 q-s0.web.default.deployment-y.bosh:8080 check inter 1000

  ha_proxy.max_open_files:
    description: The number of file descriptors HAProxy can have open at one time
    default: 256000
  ha_proxy.max_connections:
    description: Number of simultaneous connections HAProxy supports handling
    default: 64000
  ha_proxy.drain_enable:
    description: Send SIGUSR1 signal to all haproxy processes in a drain script in order to gracefully shutdown
    default: false
  ha_proxy.drain_timeout:
    description: Time in seconds after SIGUSR1 signal is sent in the drain script until monit stops the processes
    default: 30
  ha_proxy.drain_frontend_grace_time:
    description: Time in seconds after health checks have been shut down until SIGUSR1 signal is sent to make the frontends stop accepting connections
    default: 0
  ha_proxy.backend_prefer_local_az:
    description: |
      Prefer backend servers which are located on the same availability zone. Note that this only affects servers provided via the http_backend link property. Servers provided via the tcp backend_link will automatically prefer the local AZ.
    default: false
  ha_proxy.enable_http2:
    description: Enables ingress (frontend) and egress (backend) HTTP/2 ALPN negotiation. Egress (backend) HTTP protocol version may be overridden by `ha_proxy.backend_ssl`, `ha_proxy.disable_backend_http2_websockets` and `ha_proxy.backend_match_http_protocol`.
    default: false
  ha_proxy.always_allow_body_http10:
    description: Always allow a body to be sent when using HTTP/1.0. By default HAProxy denies GET/HEAD/DELETE requests with a body when using HTTP/1.0 due to potential request smuggling attacks. See https://github.com/haproxy/haproxy/commit/e136bd12a32970bc90d862d5fe09ea1952b62974
    default: false

  ha_proxy.requests_rate_limit.requests:
    description: How many requests are allowed in the given time window from one IP address. See docs/rate_limiting.md
  ha_proxy.requests_rate_limit.window_size:
    description: Window size for counting requests. See docs/rate_limiting.md
  ha_proxy.requests_rate_limit.table_size:
    description: Size of the stick table in which the IPs and counters are stored. See docs/rate_limiting.md
  ha_proxy.requests_rate_limit.block:
    description: Whether or not to block requests. See docs/rate_limiting.md
    default: false
  ha_proxy.connections_rate_limit.connections:
    description: How many connections are allowed in the given time window from one IP address. See docs/rate_limiting.md
  ha_proxy.connections_rate_limit.window_size:
    description: Window size for counting connections. See docs/rate_limiting.md
  ha_proxy.connections_rate_limit.table_size:
    description: Size of the stick table in which the IPs and counters are stored. See docs/rate_limiting.md
  ha_proxy.connections_rate_limit.block:
    description: Whether or not to block connections. See docs/rate_limiting.md
    default: false