Skip to content

haproxy job from haproxy/9.1.0

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

Github source: bac0eea or master branch

Properties

ha_proxy

accept_proxy

Turned off by default. Enforces the use of the PROXY protocol for all incoming connections to all frontends. When enabled standard tcp connections to these port no longer work.

Default
false

backend_ca_file

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

backend_crt

provides client certificate to backend server to do mutual ssl

Example
|+
  -----BEGIN CERTIFICATE-----
  ******
  -----END CERTIFICATE-----
  -----BEGIN PRIVATE KEY-----
  ******
  -----END PRIVATE KEY-----

backend_port

Listening port for Router

Default
80

backend_servers

Array of the router IPs acting as the HTTP/TCP backends (should include servers all Availability Zones being used)

Default
[]

backend_ssl

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.

Default
"off"

backend_ssl_verifyhost

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.

binding_ip

If there are multiple ethernet interfaces, specify which one to bind

Default
""

block_all

Optionally block all incoming traffic to http(s). Use in conjunction with whitelist.

Default
false

buffer_size_bytes

Buffer size to use for requests, any requests larger than this (large cookies or query strings) will result in a gateway error

Default
16384

cidr_blacklist

List of CIDRs to block for http(s). Format is string array of CIDRs or single string of base64 encoded gzip.

Example
cidr_blacklist:
- 10.0.0.0/8
- 192.168.2.0/24

cidr_whitelist

List of CIDRs to allow for http(s). Format is string array of CIDRs or single string of base64 encoded gzip.

Example
cidr_whitelist:
- 172.168.4.1/32
- 10.2.0.0/16

client_ca_file

path for CA certs to validate client certificate

Example
|+
  -----BEGIN CERTIFICATE-----
  ******
  -----END CERTIFICATE-----
  -----BEGIN PRIVATE KEY-----
  ******
  -----END PRIVATE KEY-----

client_cert

Enable haproxy mutual auth and produce a client cert header (X-Forwarded-Client-Cert) to offload mutual ssl client certificate to backend

Default
false

client_cert_ignore_err

Error code(s) to ignore from verifying a client cert during a mutual ssl handshake, in a pipe-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. See the openssl verify documentation [https://wiki.openssl.org/index.php/Manual:Verify(1)] for a full list of all error codes and their meanings.

Example
2|10|18

client_revocation_list

provide a list of revocation certs

client_timeout

Timeout (in floating point seconds) used on connections from a client to haproxy that have gone inactive

Default
30

compress_types

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
""

connect_timeout

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

crt_list

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: - ‘client_ca_file’ (replaces ha_proxy.client_ca_file) - ‘verify’ (allowed values: [none|optional|required]) - ‘ssl_ciphers’ (overrides ha_proxy.ssl_ciphers) - ‘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-----
- client_ca_file: |+
    -----BEGIN CERTIFICATE-----
    -----END CERTIFICATE-----
    -----BEGIN CERTIFICATE-----
    -----END CERTIFICATE-----
  client_revocation_list: |+
    -----BEGIN X509 CRL-----
    -----END X509 CRL-----
    -----BEGIN X509 CRL-----
    -----END X509 CRL-----
  snifilter:
  - '*.domain.tld'
  - '!secure.domain.tld'
  ssl_ciphers: AES:ALL:!aNULL:!eNULL:+RC4:@STRENGTH
  ssl_pem:
    cert_chain: |+
      -----BEGIN CERTIFICATE-----
      -----END CERTIFICATE-----
      -----BEGIN CERTIFICATE-----
      -----END CERTIFICATE-----
    private_key: |+
      -----BEGIN RSA PRIVATE KEY-----
      -----END RSA PRIVATE KEY-----
  verify: required

default_dh_param

Maximum size of DH params when generating epmehmeral keys during key exchange

Default
2048

disable_http

Disable port 80 traffic

Default
false

disable_tcp_accept_proxy

Disables the PROXY protocol on tcp backends. Only applies if ha_proxy.accept_proxy is enabled.

Default
false

disable_tls_10

Disable TLS 1.0 in HA Proxy

Default
false

disable_tls_11

Disable TLS 1.1 in HA Proxy

Default
false

disable_tls_tickets

Improve (Perfect) Forward Secrecy by disabling TLS tickets

Default
true

dns_hold

DNS Hold time

Default
10s

enable_4443

Enables port 4443 for backwards compatibility with WSS-based apps using the old CF haproxy

Default
false

enable_health_check_http

Optionally enable http health-check on haproxy_ip:8080/health. It shows 200 OK if >0 backend servers are up.

Default
false

forwarded_client_cert

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 (ordered from least to most secure): - always_forward_only: Least secure option. Always forward the XFCC header in the request, regardless of whether the client connection is mTLS. 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 XFCC header received from the client only when the client connection 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 client certificate received by HAProxy in the mTLS handshake will be forwarded in this header. Values will be base64 encoded PEM. Use this value when HAProxy is the first component to terminate TLS.

Default
sanitize_set

headers

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

health_check_port

port for http health-check

Default
8080

hsts_enable

Enables HSTS(Strict-Transport-Security Header) for all the SSL/TLS listeners

Default
false

hsts_include_subdomains

This enables the includeSubDomains flag for HSTS.

Default
false

hsts_max_age

max-age value for the Strict-Transport-Security header

Default
3.1536e+07

hsts_preload

This enables the preload flag for HSTS

Default
false

http_request_deny_conditions

List of conditions to block http requests. Each condition consists of multiple rules combined with the AND operator

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

https_redirect_all

If this is set to ‘true’, a https redirect rule for all http calls will be put in the config file

Default
false

https_redirect_domains

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
[]

internal_only_domains

Array of domains for internal-only apps/services (not hostnames for the apps/services)

Default
[]

keepalive_timeout

Timeout (in floating point seconds) applied to any connection that is in an http-keepalive state, waiting for the next request to occur

Default
0.5

log_level

Log level

Default
info

queue_timeout

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

raw_config

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.

request_timeout

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

resolvers

List of DNS servers

Example
resolvers:
- private: 10.0.0.2
- public: 8.8.8.8

routed_backend_servers

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:
    backend_ssl: verify
    backend_verifyhost: example.com
    port: 4443
    servers:
    - 10.0.0.2
    - 10.0.0.3

rsp_headers

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

server_timeout

Timeout (in floating point seconds) used on connections from haproxy to a backend, while waiting for data from the backend

Default
30

ssl_ciphers

List of SSL Ciphers that are passed to HAProxy

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

ssl_pem

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

stats_bind

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'

stats_enable

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

stats_password

Password to authenticate haproxy stats

stats_uri

URI used to access the stats UI.

Default
haproxy_stats

stats_user

User name to authenticate haproxy stats

strict_sni

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

syslog_server

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
127.0.0.1

tcp

List of mappings to perform tcp-based proxying on. See example for mapping datastructure and keys

Default
[]
Example
tcp:
- backend_port: 80
  backend_servers:
  - 10.20.10.10
  - 10.20.10.11
  backend_ssl: verify
  backend_verifyhost: example.com
  balance: roundrobin
  health_check_http: 4444
  name: wss
  port: 4443
  ssl: true

Optional port for http health check when using the tcp_backend link.

Port haproxy should listen on when using the tcp_backend link

tcp_routing

port_range

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

threads

Optional number of threads per VM

Default
1

trusted_domain_cidrs

Space separated trusted cidr blocks for internal_only_domains

Default
0.0.0.0/32

trusted_stats_cidrs

Trusted ip range that can access the stats UI

Default
0.0.0.0/32

websocket_timeout

Timeout (in floating point seconds) used on websocket/tunnel traffic, when both ends of the conversation have become inactive

Default
3600

Templates

Templates are rendered and placed onto corresponding instances during the deployment process. This job's templates will be placed into /var/vcap/jobs/haproxy/ directory (learn more).

  • bin/haproxy_ctl (from haproxy_ctl)
  • bin/monit_debugger (from monit_debugger)
  • config/backend-ca-certs.pem (from backend-ca-certs.erb)
  • config/backend-crt.pem (from backend-crt.erb)
  • config/blacklist_cidrs.txt (from blacklist_cidrs.txt.erb)
  • config/certs.ttar (from certs.ttar.erb)
  • config/client-ca-certs.pem (from client-ca-certs.erb)
  • config/client-revocation-list.pem (from client-revocation-list.erb)
  • config/haproxy.config (from haproxy.config.erb)
  • config/ssl_redirect.map (from ssl_redirect.map.erb)
  • config/whitelist_cidrs.txt (from whitelist_cidrs.txt.erb)
  • data/properties.sh (from properties.sh.erb)
  • helpers/ctl_setup.sh (from helpers/ctl_setup.sh)
  • helpers/ctl_utils.sh (from helpers/ctl_utils.sh)

Packages

Packages are compiled and placed onto corresponding instances during the deployment process. Packages will be placed into /var/vcap/packages/ directory.