Marathon-LB HAProxy endpoints

Marathon-LB automatically generates configuration information for the HAProxy program, then reloads and restarts HAProxy, as needed. Marathon-LB generates the HAProxy configuration based on application data available from the Marathon API. It can also subscribe to the Marathon Event Bus for real-time updates.

When an application starts, stops, relocates, or has any change in health status, Marathon-LB automatically regenerates the HAProxy configuration and reloads HAProxy.

Marathon-LB exposes the following endpoints on port 9090 by default.

Endpoint	Description
`public-node:9090/haproxy?stats`	The Statistics endpoint produces an HTML page that provides statistical information about the current HAProxy instance and its load balancing activity. You can view the statistics from this endpoint in your browser.
`public-node:9090/haproxy?stats;csv`	The Statistics CSV endpoint provides statistical information about the current HAProxy instance and load balancing activity as comma-separated values (CSV). In CSV format, the information can be consumed by other tools. For example, this endpoint produces the results used in the `zdd.py` script.
`public-node:9090/_haproxy_health_check`	The Health check endpoint returns 200 OK if HAProxy is healthy.
`public-node:9090/_haproxy_getconfig`	The Configuration endpoint returns the HAProxy configuration file as it was when HAProxy was started. Implemented in `getconfig.lua`.
`public-node:9090/_haproxy_getvhostmap`	The Virtual-host-to-backend endpoint returns the HAProxy virtual host to backend map if the `--haproxy-map` flag is enabled. If you are not using the `--haproxy-map` option, the endpoint returns an empty string. Implemented in `getmaps.lua`.
`public-node:9090/_haproxy_getappmap`	The App-ID-to-backend endpoint returns the HAProxy application identifier to backend map. Like `_haproxy_getvhostmap`, this endpoint requires you to enable the `--haproxy-map` option and returns an empty string otherwise. Also implemented in `getmaps.lua`.
`public-node:9090/_haproxy_getpids`	The Process identifiers endpoint returns the PIDs for all HAProxy instances within the current process namespace. The endpoint literally returns the output of $(`pidof haproxy`). Implemented in `getpids.lua`. This endpoint is also used by the `zdd.py` script to determine if connections have finished draining during a deployment.
`public-node:9090/_mlb_signal/hup`	The Reload configuration endpoint sends a SIGHUP signal to the `marathon-lb` process, causing it to fetch the running apps from Marathon and reload the `HAProxy` configuration as though an event was received from Marathon.
`public-node:9090/_mlb_signal/usr1`	The Restart configuration endpoint sends a `SIGUSR1` signal to the `marathon-lb` process, causing it to restart the `HAProxy` load balancer with the existing configuration, without checking Marathon for changes.

NOTE: The /_mlb_signal/hup and /_mlb_signal/usr1 endpoints do not function if Marathon-LB is running in poll mode. With the poll argument, Marathon-LB exits after each poll, so there is no running marathon_lb.py process to be signaled.

Marathon-LB command reference

Marathon-LB manages operations for the HAProxy program to provide high availability for applications running on high-volume websites. Marathon-LB relies on the marathon_lb.py script to perform the following key tasks:

Connects to the Marathon API to retrieve information about all running apps.
Generates and validates the Marathon-LB HAProxy configuration file settings.
Reloads the HAProxy program.

By default, Marathon-LB binds to the service port of every application and sends incoming requests to the application instances. Services are exposed on their service port as defined in their Marathon app definition. Furthermore, apps are only exposed on the load balancers that have the same load balancer group setting. The group setting is defined globally or in the app definition file by specifying the HAPROXY_GROUP label for individual applications.

Invoking marathon-lb directly

In most cases, the marathon_lb.py script runs in the background. However, you can also run the script directly from the command-line. For example, you can generate the HAProxy configuration information from Marathon by running the marathon_lb.py script for localhost:8080 with the following command:

./marathon_lb.py --marathon http://localhost:8080 --group external --strict-mode --health-check

Specifying credentials when running marathon-lb

If Marathon requires authentication, you can include a user name and password using the --auth-credentials configuration option. For example:

./marathon_lb.py --marathon http://localhost:8080 --auth-credentials=admin:password

You can also provide credentials from the VAULT if you define the following environment variables before running Marathon-LB:

VAULT_TOKEN
VAULT_HOST
VAULT_PORT
VAULT_PATH

If you set these environment variables, you should set the VAULT_PATH to the root path where your user account and password are located.

Skipping configuration validation

Running the marathon-lb.py script refreshes the haproxy.cfg configuration file. If there are any changes to the configuration file, the script automatically reloads the HAProxy program with the changes. You can skip the configuration file validation process if you don’t have HAProxy installed or if you are running HAProxy on Docker containers.

To skip validation of configuration settings, run the following command:

./marathon_lb.py --marathon http://localhost:8080 --group external --skip-validation

Viewing complete usage information

If you run the marathon-lb.py script directly from the command line, you can specify additional functionality such as sticky sessions, HTTP to HTTPS redirection, SSL offloading, virtual host support, and the configuration templates to use.

To get the full command reference, run the following command:

./marathon_lb.py --help

Running Docker commands for Marathon-LB

Marathon supports both Universal Container Runtime (using cgroups) and Docker containers and images. You can run Marathon-LB using a command similar to the following for Docker images:

docker run -e PORTS=$portnumber --net=host mesosphere/marathon-lb ...

This command uses the -e option to set the PORTS environment variable. The port number is required to allow the HAProxy program bind to this port. The -net option enables the command to connect a container to a specified network.

For example, to expose load-balanced applications from a Docker image on port 9090, you might run the following command:

docker run -e PORTS=9090 mesosphere/marathon-lb sse [other arguments]

Using server-sent events (sse)

If you specify the sse option, the Marathon-LB script connects to the Marathon events endpoint to get notified about state changes. You can use a command similar to the following to capture server-sent events (sse).

docker run mesosphere/marathon-lb sse [other arguments]

Determining the current status for Marathon-LB instances

If you can’t use the HTTP callbacks, you can run a command similar to the following to poll the scheduler state periodically:

docker run mesosphere/marathon-lb poll [other args]

You can also use environment variables to set other configuration options for Marathon-LB. For example, you can set the POLL_INTERVAL environment variable to change the poll interval from its default of 60 seconds.

Usage and command arguments

You can run the Marathon load balancer script (marathon_lb.py) directly from the command-line in a shell terminal or programmatically. The script accepts the following command-line options and arguments.

Usage

marathon_lb.py [-h] [--longhelp] [--marathon MARATHON [MARATHON ...]]
                      [--haproxy-config HAPROXY_CONFIG] [--group GROUP]
                      [--command COMMAND]
                      [--max-reload-retries MAX_RELOAD_RETRIES]
                      [--reload-interval RELOAD_INTERVAL] [--strict-mode]
                      [--sse] [--archive-versions ARCHIVE_VERSIONS]
                      [--health-check]
                      [--lru-cache-capacity LRU_CACHE_CAPACITY]
                      [--haproxy-map] [--dont-bind-http-https]
                      [--group-https-by-vhost] [--ssl-certs SSL_CERTS]
                      [--skip-validation] [--dry]
                      [--min-serv-port-ip-per-task MIN_SERV_PORT_IP_PER_TASK]
                      [--max-serv-port-ip-per-task MAX_SERV_PORT_IP_PER_TASK]
                      [--syslog-socket SYSLOG_SOCKET]
                      [--log-format LOG_FORMAT] [--log-level LOG_LEVEL]
                      [--marathon-auth-credential-file MARATHON_AUTH_CREDENTIAL_FILE]
                      [--auth-credentials AUTH_CREDENTIALS]
                      [--dcos-auth-credentials DCOS_AUTH_CREDENTIALS]
                      [--marathon-ca-cert MARATHON_CA_CERT]

Required arguments

Argument	Description
-m, --marathon MARATHON [MARATHON ...]	Specifies one or more Marathon endpoints. This argument specifies the location of the Marathon containers for Marathon-LB to use. The default endpoint is http://master.mesos:8080. For example, you can use this argument to specify two Marathon instances like this: -m http://marathon1:8080 http://marathon2:8080.
--group GROUP	Generates configuration information only for the apps with the specified group names. Use `*` to match all groups, including groups without a group name specified. The default is an empty string.

Optional arguments

Argument	Description
-h, --help	Show this help message and exit.
--longhelp	Print out configuration details. The default is false.
--haproxy-config HAPROXY_CONFIG	Specifies the location of the `haproxy` configuration file. The default is /etc/haproxy/haproxy.cfg
--command COMMAND, -c COMMAND	If set, run this command to reload haproxy. The default is none.
--max-reload-retries MAX_RELOAD_RETRIES	Specifies the maximum number if reload retries before failure. Reloads happen every --reload-interval seconds. Set to 0 to disable reloading attempts or -1 for infinite retries. The default is 10.
--reload-interval RELOAD_INTERVAL	Waits the specified number of seconds between reload retries. The default is 10.
--strict-mode	Enables backends to be advertised only if HAPROXY_{n}_ENABLED=true. Strict mode might be enabled by default in a future release. The default is false.
--sse, -s	Uses server-sent events. The default is false.
--archive-versions ARCHIVE_VERSIONS	Specifies the number of configuration versions to archive. The default is 5.
--health-check, -H	Determines Marathon's health check status before adding the app instance into the backend pool. The default is false.
--lru-cache-capacity LRU_CACHE_CAPACITY	Specifies the LRU cache size (in number of items). This argument should be at least as large as the number of tasks exposed to marathon-lb. The default is 1000.
--haproxy-map	Uses HAProxy maps for domain name to backend mapping. The default is false.
--dont-bind-http-https	Prevents binding to HTTP and HTTPS frontends. The default is false.
--group-https-by-vhost	Groups https frontends by virtual host. The default is false.
--ssl-certs SSL_CERTS	Lists SSL certificates separated by commas for frontend marathon_https_in. The default is /etc/ssl/cert.pem. For example: /etc/ssl/site1.co.pem,/etc/ssl/site2.co.pem
--skip-validation	Skips haproxy configuration file validation. The default is false.
--dry, -d	Only prints configuration information to the console. The default is false.
--min-serv-port-ip-per-task MIN_SERV_PORT_IP_PER_TASK	Specifies the minimum port number to use when auto-assigning service ports for IP-per-task applications. The default is 10050.
--max-serv-port-ip-per-task MAX_SERV_PORT_IP_PER_TASK	Specifies the maximum port number to use when auto-assigning service ports for IP-per-task applications. The default is 10100.
--syslog-socket SYSLOG_SOCKET	Specifies the socket to write syslog messages to. Use /dev/null to disable logging to syslog. The default is /dev/log.
-log-format LOG_FORMAT	Sets the log message format. The default is %(asctime)-15s %(name)s: %(message)s.
--log-level LOG_LEVEL	Sets the log level, The default is DEBUG.
--marathon-auth-credential-file MARATHON_AUTH_CREDENTIAL_FILE	Specifies the path to file containing a user name and password for the Marathon HTTP API in the format of user:pass. The default is none.
--auth-credentials AUTH_CREDENTIALS	Specifies the user name and password for the Marathon HTTP API in the format of user:pass. The default is none.
--dcos-auth-credentials DCOS_AUTH_CREDENTIALS	Specifies the DC/OS service account credentials. The default is none.
--dcos-auth-credentials DCOS_AUTH_CREDENTIALS	Specifies the DC/OS service account credentials. The default is none.
--marathon-ca-cert MARATHON_CA_CERT	Specifies the CA certificate for Marathon HTTPS connections. The default is none.

Template and label reference

The following is a list of the available HAProxy configuration templates. Some templates are global-only (such as HAPROXY_HEAD), but most can be specified on a per service port basis as app labels to override the global settings.

The templates and app labels that can be set per-service-port include an index identifier {n} in the template or label name. The index identifier corresponds to the service port index, beginning at 0, to which the app label applies. For example, you could specify HAPROXY_0_BACKEND_HEAD to override the global template HAPROXY_BACKUP_HEAD for the first port of a given application.

Backend template settings

Use the following template and app labels to configure backend settings for the load balancer.

Template name	Description and examples
`HAPROXY_BACKEND_HEAD`	Defines the type of load balancing and the connection mode for a backend. The default load balancing type (algorithm) is `roundrobin`. The default connection mode is `tcp`. The valid values for the load balancing type include: `roundrobin` - Each server is used in turns, according to their weights. This algorithm is dynamic and ensures processing time remains equally distributed. `static-rr` - Each server is used in turns, according to their weights. This algorithm is as similar to roundrobin except that it is static. `leastconn` - The server with the least number of connections receives the next connection request. Round-robin selection is performed within groups of servers that have the same load to ensure that all servers are used. This algorithm is recommended when long sessions, such as LDAP or SQL sessions are expected, is not appropriate for protocols using short sessions such as HTTP. `source` - The source IP address is hashed and divided by the total weight of the running servers to designate which server should receive the request. This algorithm ensures that the same client IP address always reaches the same server as long as no server goes down or up. If the hash result changes because the number of running servers has changed, clients are directed to a different server. This algorithm is generally used with TCP mode or for clients that refuse session cookies. `uri` - This algorithm hashes either the left part of the URI (before the question mark) or the whole URI (if the “whole” parameter is present) and divides the hash value by the total weight of the running servers. The result designates which server receives the request. You can set the connection mode to `tcp`, `http`, or `health`. The default template for `HAPROXY_BACKEND_HEAD` is: `backend {backend} balance {balance} mode {mode}` You can override this template using the following app label for the first port (`0`) of a given app: `“HAPROXY_0_BACKEND_HEAD”: “\nbackend {backend}\n balance {balance}\n mode {mode}\n”`
`HAPROXY_BACKEND_HSTS _OPTIONS`	Specifies the backend options to use where the `HAPROXY_{n}_USE_HSTS` app label that enables the HSTS response header for HTTP clients is set to true. The default template for `HAPROXY_BACKEND_HSTS_OPTIONS` is: `rspadd Strict-Transport-Security:\ max-age=15768000` You can override this template using the following app label for the first port (`0`) of a given app: `“HAPROXY_0_BACKEND_HSTS_OPTIONS”: " rspadd Strict-Transport-Security:\ max-age=15768000\n"`
`HAPROXY_BACKEND_HTTP _HEALTHCHECK_OPTIONS`	Sets HTTP health check options, such as the health check timeout interval and consecutive failures allowed. The valid options for the first health check or the first health check for a given service are exposed as follows: healthCheckPortIndex healthCheckPort healthCheckProtocol healthCheckPath healthCheckTimeoutSeconds healthCheckIntervalSeconds healthCheckGracePeriodSeconds healthCheckMaxConsecutiveFailures healthCheckFalls (healthCheckMaxConsecutiveFailures + 1) healthCheckPortOptions (port {healthCheckPort}) The default template for `HAPROXY_BACKEND_HTTP_HEALTHCHECK_OPTIONS` is: `option httpchk GET {healthCheckPath timeout check {healthCheckTimeoutSeconds}s` You can override this template using the following app label for the first port (`0`) of a given app: `“HAPROXY_0_BACKEND_HTTP_HEALTHCHECK_OPTIONS”: " option httpchk GET {healthCheckPath}\n timeout check {healthCheckTimeoutSeconds}s\n"`
`HAPROXY_BACKEND_HTTP _OPTIONS`	Sets HTTP headers, for example, X-Forwarded-For and X-Forwarded-Proto. The default template for `HAPROXY_BACKEND_HTTP_OPTIONS` is: `option forwardfor http-request set-header X-Forwarded-Port %[dst_port] http-request add-header X-Forwarded-Proto https if { ssl_fc }` You can override this template using the following app label for the first port (`0`) of a given app: `“HAPROXY_0_BACKEND_HTTP_OPTIONS”: " option forwardfor\n http-request set-header X-Forwarded-Port %[dst_port]\n http-request add-header X-Forwarded-Proto https if { ssl_fc }\n"`
`HAPROXY_BACKEND_REDIRECT _HTTP_TO_HTTPS`	Redirects backends if the HAPROXY_{n}_REDIRECT_TO_HTTPS label is set to true. The default template for `HAPROXY_BACKEND_REDIRECT_HTTP_TO_HTTPS` is: `redirect scheme https code 301 if !{{ ssl_fc }} host_{cleanedUpHostname}` You can override this template with the following app label for the first port (`0`) of a given app: `HAPROXY_0_BACKEND_REDIRECT_HTTP_TO_HTTPS": " redirect scheme https code 301 if !{{ ssl_fc }} host_{cleanedUpHostname}\n"`
`HAPROXY_BACKEND_REDIRECT _HTTP_TO_HTTPS_WITH_PATH`	Redirects backends if the `HAPROXY_{n}_REDIRECT_TO_HTTPS_WITH_PATH` label is set to true, but includes a path. The default template for `HAPROXY_BACKEND_REDIRECT_HTTP_TO_HTTPS_WITH_PATH` is: `redirect scheme https code 301 if !{{ ssl_fc }} host_{cleanedUpHostname} path_{backend}` You can override this template with the following app label for the first port (`0`) of a given app: `“HAPROXY_0_BACKEND_REDIRECT_HTTP_TO_HTTPS_WITH_PATH”: " redirect scheme https code 301 if !{{ ssl_fc }} host_{cleanedUpHostname} path_{backend}\n"`
`HAPROXY_BACKEND_SERVER _HTTP_HEALTHCHECK_OPTIONS`	Sets HTTP health check options, such as the health check timeout interval, for a single server. The valid options for the first health check or the first health check for a given service are exposed as follows: healthCheckPortIndex healthCheckPort healthCheckProtocol healthCheckPath healthCheckTimeoutSeconds healthCheckIntervalSeconds healthCheckGracePeriodSeconds healthCheckMaxConsecutiveFailures healthCheckFalls (healthCheckMaxConsecutiveFailures + 1) healthCheckPortOptions (port {healthCheckPort}) The default template for `HAPROXY_BACKEND_SERVER_HTTP_HEALTHCHECK_OPTIONS` is: `check inter {healthCheckIntervalSeconds}s fall {healthCheckFalls}{healthCheckPortOptions}` You can override this template with the following app label for the first port (`0`) of a given app: `“HAPROXY_0_BACKEND_SERVER_HTTP_HEALTHCHECK_OPTIONS”: " check inter {healthCheckIntervalSeconds}s fall {healthCheckFalls}{healthCheckPortOptions}\n"`
`HAPROXY_BACKEND_SERVER _OPTIONS`	Specifies the options for each server added to a backend. The default template for HAPROXY_BACKEND_SERVER_OPTIONS is: `server {serverName} {host_ipv4}:{port}{cookieOptions}{healthCheckOptions}{otherOptions}` You can override this template with the following app label for the first port (`0`) of a given app: `“HAPROXY_0_BACKEND_SERVER_OPTIONS”: " server {serverName} {host_ipv4}:{port}{cookieOptions}{healthCheckOptions}{otherOptions}\n"`
`HAPROXY_BACKEND_SERVER _TCP_HEALTHCHECK _OPTIONS`	Sets TCP health check options, such as the health check timeout interval, for a single server. The valid options for the first health check or the first health check for a given service are exposed as follows: healthCheckPortIndex healthCheckPort healthCheckProtocol healthCheckTimeoutSeconds healthCheckIntervalSeconds healthCheckGracePeriodSeconds healthCheckMaxConsecutiveFailures healthCheckFalls (healthCheckMaxConsecutiveFailures + 1) healthCheckPortOptions (port {healthCheckPort}) The default template for `HAPROXY_BACKEND_SERVER_TCP_HEALTHCHECK_OPTIONS` is: `check inter {healthCheckIntervalSeconds}s fall {healthCheckFalls}{healthCheckPortOptions}` You can override this template with the following app label for the first port (`0`) of a given app: `“HAPROXY_0_BACKEND_SERVER_TCP_HEALTHCHECK_OPTIONS”: " check inter {healthCheckIntervalSeconds}s fall {healthCheckFalls}{healthCheckPortOptions}\n"`
`HAPROXY_BACKEND_STICKY_OPTIONS`	Sets a cookie for services where HAPROXY_{n}_STICKY is true. The default template for `HAPROXY_BACKEND_STICKY_OPTIONS` is: `cookie mesosphere_server_id insert indirect nocache` You can override this template with the following app label for the first port (`0`) of a given app: `“HAPROXY_0_BACKEND_STICKY_OPTIONS”: " cookie mesosphere_server_id insert indirect nocache\n"`
`HAPROXY_BACKEND_TCP _HEALTHCHECK_OPTIONS`	Sets TCP health check options,such as the timeout check. The valid options for the first health check or the first health check for a given service are exposed as follows: healthCheckPortIndex healthCheckPort healthCheckProtocol healthCheckTimeoutSeconds healthCheckIntervalSeconds healthCheckGracePeriodSeconds healthCheckMaxConsecutiveFailures healthCheckFalls (healthCheckMaxConsecutiveFailures + 1) healthCheckPortOptions (port {healthCheckPort}) The default template for `HAPROXY_BACKEND_TCP_HEALTHCHECK_OPTIONS` is an empty string. The following example sets a timeout check: `timeout check {healthCheckTimeoutSeconds}s` You can override this template with the following app label for the first port (`0`) of a given app: `“HAPROXY_0_BACKEND_TCP_HEALTHCHECK_OPTIONS”: “”`
`HAPROXY_HTTPS_GROUPED _VHOST_BACKEND_HEAD`	Defines the HTTPS backend for vhost. You must enable the `group-https-by-vhost` option to use this setting. This template is a global template that cannot be modified by service port or per application. The default template for `HAPROXY_HTTPS_GROUPED_VHOST_BACKEND_HEAD` is: `backend {name} server loopback-for-tls abns@{name} send-proxy-v2`
`HAPROXY_HTTP_BACKEND _ACL_ALLOW_DENY`	Denies access for all IP addresses (or IP ranges) that are not explicitly allowed to access the HTTP backend. Use this template with HAPROXY_HTTP_BACKEND_NETWORK_ALLOWED_ACL. This template is a global template that cannot be modified by service port or per application. The default template for `HAPROXY_HTTP_BACKEND_ACL_ALLOW_DENY` is: `http-request allow if network_allowed http-request deny`
`HAPROXY_HTTP_BACKEND _NETWORK_ALLOWED_ACL`	Specifies the IP addresses (or IP ranges) that have access to the HTTP backend. This template is a global template that cannot be modified by service port or per application. The default template for `HAPROXY_HTTP_BACKEND_NETWORK_ALLOWED_ACL` is: `acl network_allowed src {network_allowed}` You can override this template with the following app label for the first port (`0`) of a given app: `“HAPROXY_0_HTTP_BACKEND_NETWORK_ALLOWED_ACL”: " acl network_allowed src {network_allowed}\n"`
`HAPROXY_HTTP_BACKEND _PROXYPASS_GLUE`	Specifies the backend glue for HAPROXY_{n}_HTTP_BACKEND_PROXYPASS_PATH. The default template for `HAPROXY_HTTP_BACKEND_PROXYPASS_GLUE` is: `http-request set-header Host {hostname} reqirep “^([^ :])\ {proxypath}/?(.)” “\1\ /\2”` You can override this template with the following app label for the first port (`0`)of a given app: `“HAPROXY_0_HTTP_BACKEND_PROXYPASS_GLUE”: " http-request set-header Host {hostname}\n reqirep “^([^ :])\ {proxypath}/?(.)” “\1\ /\2”\n"`
`HAPROXY_HTTP_BACKEND_REDIR`	Sets the path to which you want to redirect the root of the domain. The default template for `HAPROXY_HTTP_BACKEND_REDIR` is: `acl is_root path -i / acl is_domain hdr(host) -i {hostname} redirect code 301 location {redirpath} if is_domain is_root` You can override this template with the following app label for the first port (`0`) of a given app: `“HAPROXY_0_HTTP_BACKEND_REDIR”: " acl is_root path -i /\n acl is_domain hdr(host) -i {hostname}\n redirect code 301 location {redirpath} if is_domain is_root\n"`
`HAPROXY_HTTP_BACKEND _REVPROXY_GLUE`	Specifies the backend glue for HAPROXY_{n}_HTTP_BACKEND_REVPROXY_PATH. The default template for `HAPROXY_HTTP_BACKEND_REVPROXY_GLUE` is: `acl hdr_location res.hdr(Location) -m found rspirep “^Location: (https?://{hostname}(:[0-9]+)?)?(/.)” “Location: {rootpath} if hdr_location”` You can override this template with the following app label for the first port (`0`)of a given app: `“HAPROXY_0_HTTP_BACKEND_REVPROXY_GLUE”: " acl hdr_location res.hdr(Location) -m found\n rspirep “^Location: (https?://{hostname}(:[0-9]+)?)?(/.)” “Location: {rootpath} if hdr_location”\n"`
`HAPROXY_TCP_BACKEND _ACL_ALLOW_DENY`	Denies access for all IP addresses (or IP address ranges) that are not explicitly allowed to access the TCP backend. This global template cannot be overridden by service port or application. The default template for `HAPROXY_TCP_BACKEND_ACL_ALLOW_DENY` is: `tcp-request content accept if network_allowed tcp-request content reject`
`HAPROXY_TCP_BACKEND _NETWORK_ALLOWED_ACL`	Specifies the IP addresses (or IP address ranges) that have been granted access to the TCP backend. The default template for `HAPROXY_TCP_BACKEND_NETWORK_ALLOWED_ACL` is: `acl network_allowed src {network_allowed}` You can override this template with the following app label for the first port (`0`) of a given app: `“HAPROXY_0_TCP_BACKEND_NETWORK_ALLOWED_ACL”: " acl network_allowed src {network_allowed}\n"`

Frontend template settings

Use the following template and app labels to configure frontend settings for the load balancer.

Template name	Description and examples
`HAPROXY_FRONTEND_BACKEND_GLUE`	Glues the backend to the frontend. The default template for `HAPROXY_FRONTEND_BACKEND_GLUE` is: `use_backend {backend}` You can override this template with the following app label for the first port (`0`) of a given app: `“HAPROXY_0_FRONTEND_BACKEND_GLUE”: " use_backend {backend}\n"`
`HAPROXY_FRONTEND_HEAD`	Defines the address and port to bind to for this frontend. The default template for `HAPROXY_FRONTEND_HEAD` is: `frontend {backend} bind {bindAddr}:{servicePort}{sslCert}{bindOptions} mode {mode}` You can override this template with the following app label for the first port (`0`) of a given app: `“HAPROXY_0_FRONTEND_HEAD”: “\nfrontend {backend}\n bind {bindAddr}:{servicePort}{sslCert}{bindOptions}\n mode {mode}\n”`
`HAPROXY_HTTPS_FRONTEND _ACL`	Specifies the ACL that performs the SNI based hostname matching for the HAPROXY_HTTPS_FRONTEND_HEAD template. The default template for `HAPROXY_HTTPS_FRONTEND_ACL` is: `use_backend {backend} if {{ ssl_fc_sni {hostname} }}` You can override this template with the following app label for the first port (`0`) of a given app: `“HAPROXY_0_HTTPS_FRONTEND_ACL”: " use_backend {backend} if {{ ssl_fc_sni {hostname} }}\n"`
`HAPROXY_HTTPS_FRONTEND _ACL_ONLY_WITH_PATH`	Defines the access control list (ACL) frontend that matches a particular host name with a path. This template is similar to HTTP_FRONTEND_ACL_ONLY_WITH_PATH, but is only applicable for HTTPS requests. The default template for `HAPROXY_HTTPS_FRONTEND_ACL_ONLY_WITH_PATH` is: `acl path_{backend} path_beg {path}` You can override this template with the following app label for the first port (`0`) of a given app: `“HAPROXY_0_HTTPS_FRONTEND_ACL_ONLY_WITH_PATH”: " acl path_{backend} path_beg {path}\n"`
`HAPROXY_HTTPS_FRONTEND _ACL_WITH_AUTH`	Specifies the access control list (ACL) that glues a backend to the corresponding virtual host of the HAPROXY_HTTPS_FRONTEND_HEAD through HTTP Basic authentication. The default template for `HAPROXY_HTTPS_FRONTEND_ACL_WITH_AUTH` is: `acl auth_{cleanedUpHostname} http_auth(user_{backend}) http-request auth realm “{realm}” if {{ ssl_fc_sni {hostname} }} !auth_{cleanedUpHostname} use_backend {backend} if {{ ssl_fc_sni {hostname} }}` You can override this template with the following app label for the first port (`0`) of a given app: `“HAPROXY_0_HTTPS_FRONTEND_ACL_WITH_AUTH”: " acl auth_{cleanedUpHostname} http_auth(user_{backend})\n http-request auth realm “{realm}” if {{ ssl_fc_sni {hostname} }} !auth_{cleanedUpHostname}\n use_backend {backend} if {{ ssl_fc_sni {hostname} }}\n"`
`HAPROXY_HTTPS_FRONTEND _ACL_WITH_AUTH _AND_PATH`	Specifies the ACL that glues a backend to the corresponding virtual host with path of the HAPROXY_HTTPS_FRONTEND_HEAD through HTTP Basic authentication. The default template for `HAPROXY_HTTPS_FRONTEND_ACL_WITH_AUTH_AND_PATH` is: `acl auth_{cleanedUpHostname} http_auth(user_{backend}) http-request auth realm “{realm}” if {{ ssl_fc_sni {hostname} }} path_{backend} !auth_{cleanedUpHostname} use_backend {backend} if {{ ssl_fc_sni {hostname} }} path_{backend}` You can override this template with the following app label for the first port (`0`) of a given app: `“HAPROXY_0_HTTPS_FRONTEND_ACL_WITH_AUTH_AND_PATH”: " acl auth_{cleanedUpHostname} http_auth(user_{backend})\n http-request auth realm “{realm}” if {{ ssl_fc_sni {hostname} }} path_{backend} !auth_{cleanedUpHostname}\n use_backend {backend} if {{ ssl_fc_sni {hostname} }} path_{backend}\n"`
`HAPROXY_HTTPS_FRONTEND _ACL_WITH_PATH`	Specifies the ACL that performs the SNI based hostname matching with path for the HAPROXY_HTTPS_FRONTEND_HEAD template. The default template for `HAPROXY_HTTPS_FRONTEND_ACL_WITH_PATH` is: `use_backend {backend} if {{ ssl_fc_sni {hostname} }} path_{backend}` You can override this template with the following app label for the first port (`0`) of a given app: `“HAPROXY_0_HTTPS_FRONTEND_ACL_WITH_PATH”: " use_backend {backend} if {{ ssl_fc_sni {hostname} }} path_{backend}\n"`
`HAPROXY_HTTPS_FRONTEND _AUTH_ACL_ONLY`	Specifies the HTTP authentication ACL for the corresponding virtual host. The default template for `HAPROXY_HTTPS_FRONTEND_AUTH_ACL_ONLY` is: `acl auth_{cleanedUpHostname} http_auth(user_{backend})` `You can override this template with the following app label for the first port (0) of a given app: “HAPROXY_0_HTTPS_FRONTEND_AUTH_ACL_ONLY”: " acl auth_{cleanedUpHostname} http_auth(user_{backend})\n"`
`HAPROXY_HTTPS_FRONTEND _AUTH_REQUEST_ONLY`	Specifies the HTTP authentication request forthe corresponding virtual host. The default template for `HAPROXY_HTTPS_FRONTEND_AUTH_REQUEST_ONLY` is: `http-request auth realm “{realm}” if {{ ssl_fc_sni {hostname} }} !auth_{cleanedUpHostname}` You can override this template with the following app label for the first port (`0`) of a given app: `“HAPROXY_0_HTTPS_FRONTEND_AUTH_REQUEST_ONLY”: " http-request auth realm “{realm}” if {{ ssl_fc_sni {hostname} }} !auth_{cleanedUpHostname}\n"`
`HAPROXY_HTTPS_FRONTEND_HEAD`	Specifies an HTTPS frontend for encrypted connections that binds to port :443 by default and gathers all virtual hosts as defined by the HAPROXY_{n}_VHOST label. This template is a global template that cannot be modified by service port or per application. You must modify this template setting if you want to include your SSL certificate. The default template for `HAPROXY_HTTPS_FRONTEND_HEAD` is: `frontend marathon_https_in bind :443 ssl {sslCerts} mode http`
`HAPROXY_HTTPS_FRONTEND _ROUTING_ONLY_WITH _PATH_AND_AUTH`	Works in combination with HAPROXY_HTTP_FRONTEND_ACL_ONLY_WITH_PATH to glue ACL names to the appropriate backend. The default template for `HAPROXY_HTTPS_FRONTEND_ROUTING_ONLY_WITH_PATH_AND_AUTH` is: `http-request auth realm "{realm}" if host_{cleanedUpHostname} path_{backend} !auth_{cleanedUpHostname} use_backend {backend} if host_{cleanedUpHostname} path_{backend}` You can override this template with the following app label for the first port (`0`) of a given app: `“HAPROXY_0_HTTPS_FRONTEND_ROUTING_ONLY_WITH_PATH_AND_AUTH”: " http-request auth realm “{realm}” if host_{cleanedUpHostname} path_{backend} !auth_{cleanedUpHostname}\n use_backend {backend} if host_{cleanedUpHostname} path_{backend}\n"`
`HAPROXY_HTTPS_GROUPED _FRONTEND_HEAD`	Defines the HTTPS frontend for encrypted connections that binds to port :443 by default and gathers all virtual hosts as defined by the HAPROXY_{n}_VHOST label. This template is useful for adding client certificates per domain. You must enable the `group-https-by-vhost` option to use this setting. This template is a global template that cannot be modified by service port or per application. The default template for `HAPROXY_HTTPS_GROUPED_FRONTEND_HEAD` is: `frontend marathon_https_in bind :443 mode tcp tcp-request inspect-delay 5s tcp-request content accept if { req_ssl_hello_type 1 }`
`HAPROXY_HTTPS_GROUPED _VHOST_FRONTEND_ACL`	Specifies a route rule HTTPS entrypoint. You must enable the `group-https-by-vhost` option to use this setting. This template is a global template that cannot be modified by service port or per application. The default template for `HAPROXY_HTTPS_GROUPED_VHOST_FRONTEND_ACL` is: `use_backend {backend} if {{ req_ssl_sni -i {host} }}`
`HAPROXY_HTTPS_GROUPED _VHOST_FRONTEND_HEAD`	Specifies the HTTPS frontend for the virtual host. You must enable the `group-https-by-vhost` option to use this setting. This template is a global template that cannot be modified by service port or per application. The default template for `HAPROXY_HTTPS_GROUPED_VHOST_FRONTEND_HEAD` is: `frontend {name} mode http bind abns@{name} accept-proxy ssl {sslCerts}{bindOpts}`
`HAPROXY_HTTP_FRONTEND_ACL`	Specifies the access control list (ACL) that glues a backend to the corresponding virtual host of the HAPROXY_HTTP_FRONTEND_HEAD. The default template for `HAPROXY_HTTP_FRONTEND_AC`L` is: `acl host_{cleanedUpHostname} hdr(host) -i {hostname} use_backend {backend} if host_{cleanedUpHostname}` You can override this template with the following app label for the first port (`0`) of a given app: `“HAPROXY_0_HTTP_FRONTEND_ACL”: " acl host_{cleanedUpHostname} hdr(host) -i {hostname}\n use_backend {backend} if host_{cleanedUpHostname}\n"`
`HAPROXY_HTTP_FRONTEND _ACL_ONLY`	Defines the access control list (ACL) that matches a particular host name. Unlike HAPROXY_HTTP_FRONTEND_ACL, this template only includes the ACL portion. It does not glue the access control list (ACL) to the backend. You should only use this template if you have multiple virtual hosts routing to the same backend. The default template for `HAPROXY_HTTP_FRONTEND_ACL_ONLY` is: `acl host_{cleanedUpHostname} hdr(host) -i {hostname}` You can override this template with the following app label for the first port (`0`) of a given app: `“HAPROXY_0_HTTP_FRONTEND_ACL_ONLY”: " acl host_{cleanedUpHostname} hdr(host) -i {hostname}\n"`
`HAPROXY_HTTP_FRONTEND _ACL_ONLY_WITH_PATH`	Defines the access control list (ACL) that matches a particular host name with a path. Unlike HAPROXY_HTTP_FRONTEND_ACL_WITH_PATH, this template only includes the ACL portion. It does not glue the access control list (ACL) to the backend. You should only use this template if you have multiple virtual hosts routing to the same backend. The default template for `HAPROXY_HTTP_FRONTEND_ACL_ONLY_WITH_PATH` is: `acl path_{backend} path_beg {path}` You can override this template with the following app label for the first port (`0`) of a given app: `“HAPROXY_0_HTTP_FRONTEND_ACL_ONLY_WITH_PATH”: " acl path_{backend} path_beg {path}\n"`
`HAPROXY_HTTP_FRONTEND _ACL_ONLY_WITH _PATH_AND_AUTH`	Defines the access control list (ACL) that matches a particular host name with a path and authentication method. Unlike HAPROXY_HTTP_FRONTEND_ACL_WITH_PATH, this template only includes the ACL portion. It does not glue the access control list (ACL) to the backend. You should only use this template if you have multiple virtual hosts routing to the same backend. The default template for `HAPROXY_HTTP_FRONTEND_ACL_ONLY_WITH_PATH_AND_AUTH` is: `acl path_{backend} path_beg {path} acl auth_{cleanedUpHostname} http_auth(user_{backend})` You can override this template with the following app label for the first port (`0`) of a given app: `“HAPROXY_0_HTTP_FRONTEND_ACL_ONLY_WITH_PATH_AND_AUTH”: " acl path_{backend} path_beg {path}\n acl auth_{cleanedUpHostname} http_auth(user_{backend})\n"`
`HAPROXY_HTTP_FRONTEND _ACL_WITH_AUTH`	Specifies the access control list (ACL) that glues a backend to the corresponding virtual host specified by the HAPROXY_HTTP_FRONTEND_HEAD setting through HTTP Basic authentication. The default template for `HAPROXY_HTTP_FRONTEND_ACL_WITH_AUTH` is: `acl host_{cleanedUpHostname} hdr(host) -i {hostname} acl auth_{cleanedUpHostname} http_auth(user_{backend}) http-request auth realm “{realm}” if host_{cleanedUpHostname} !auth_{cleanedUpHostname} use_backend {backend} if host_{cleanedUpHostname}` `You can override this template with the following app label for the first port (0) of a given app: “HAPROXY_0_HTTP_FRONTEND_ACL_WITH_AUTH”: " acl host_{cleanedUpHostname} hdr(host) -i {hostname}\n acl auth_{cleanedUpHostname} http_auth(user_{backend})\n http-request auth realm “{realm}” if host_{cleanedUpHostname} !auth_{cleanedUpHostname}\n use_backend {backend} if host_{cleanedUpHostname}\n"`
`HAPROXY_HTTP_FRONTEND _ACL_WITH_AUTH _AND_PATH`	Specifies the access control list (ACL) that glues a backend to the corresponding virtual host with the path specified by the HAPROXY_HTTP_FRONTEND_HEAD setting through HTTP Basic authentication. The default template for `HAPROXY_HTTP_FRONTEND_ACL_WITH_AUTH_AND_PATH` is: `acl host_{cleanedUpHostname} hdr(host) -i {hostname} acl auth_{cleanedUpHostname} http_auth(user_{backend}) acl path_{backend} path_beg {path} http-request auth realm “{realm}” if host_{cleanedUpHostname} path_{backend} !auth_{cleanedUpHostname} use_backend {backend} if host_{cleanedUpHostname} path_{backend}` You can override this template with the following app label for the first port (`0`) of a given app: `“HAPROXY_0_HTTP_FRONTEND_ACL_WITH_AUTH_AND_PATH”: " acl host_{cleanedUpHostname} hdr(host) -i {hostname}\n acl auth_{cleanedUpHostname} http_auth(user_{backend})\n acl path_{backend} path_beg {path}\n http-request auth realm “{realm}” if host_{cleanedUpHostname} path_{backend} !auth_{cleanedUpHostname}\n use_backend {backend} if host_{cleanedUpHostname} path_{backend}\n"`
`HAPROXY_HTTP_FRONTEND _ACL_WITH_PATH`	Specifies the access control list (ACL) that glues a backend to the corresponding virtual host with the path specified by the HAPROXY_HTTP_FRONTEND_HEAD setting. The default template for `HAPROXY_HTTP_FRONTEND_ACL_WITH_PATH` is: `acl host_{cleanedUpHostname} hdr(host) -i {hostname} acl path_{backend} path_beg {path} use_backend {backend} if host_{cleanedUpHostname} path_{backend}` You can override this template with the following app label for the first port (`0`) of a given app: `“HAPROXY_0_HTTP_FRONTEND_ACL_WITH_PATH”: " acl host_{cleanedUpHostname} hdr(host) -i {hostname}\n acl path_{backend} path_beg {path}\n use_backend {backend} if host_{cleanedUpHostname} path_{backend}\n"`
`HAPROXY_HTTP_FRONTEND _APPID_ACL`	Specifies the access control list (ACL) that glues a backend to the corresponding app specified by the HAPROXY_HTTP_FRONTEND_APPID_HEAD setting. The default template for `HAPROXY_HTTP_FRONTEND_APPID_ACL` is: `acl app_{cleanedUpAppId} hdr(x-marathon-app-id) -i {appId} use_backend {backend} if app_{cleanedUpAppId}` You can override this template with the following app label for the first port (`0`) of a given app: `“HAPROXY_0_HTTP_FRONTEND_APPID_ACL”: " acl app_{cleanedUpAppId} hdr(x-marathon-app-id) -i {appId}\n use_backend {backend} if app_{cleanedUpAppId}\n"`
`HAPROXY_HTTP_FRONTEND _APPID_HEAD`	Specifies the HTTP frontend that binds to port :9091 by default and gathers all apps in HTTP mode. To use this frontend to forward to your app, configure the app with HAPROXY_0_MODE=http then you can access it via a call to the :9091 with the header "X-Marathon-App-Id" set to the Marathon AppId. Note multiple HTTP ports being exposed by the same marathon app are not supported. Only the first HTTP port is available using this frontend. This template is a global template that cannot be modified by service port or per application. The default template for `HAPROXY_HTTP_FRONTEND_APPID_HEAD` is: `frontend marathon_http_appid_in bind :9091 mode http`
`HAPROXY_HTTP_FRONTEND_HEAD`	Specifies the HTTP frontend that binds to port :80 by default and gathers all virtual hosts as defined by the HAPROXY_{n}_VHOST label. This template is a global template that cannot be modified by service port or per application. The default template for `HAPROXY_HTTP_FRONTEND_HEAD` is: `frontend marathon_http_in bind :80 mode http`
`HAPROXY_HTTP_FRONTEND _ROUTING_ONLY`	Works in combination with the HAPROXY_HTTP_FRONTEND_ACL_ONLY setting to map access control list (ACL) names to their appropriate backends. The default template for `HAPROXY_HTTP_FRONTEND_ROUTING_ONLY` is: `use_backend {backend} if host_{cleanedUpHostname}` You can override this template with the following app label for the first port (`0`) of a given app: `“HAPROXY_0_HTTP_FRONTEND_ROUTING_ONLY”: " use_backend {backend} if host_{cleanedUpHostname}\n"`
`HAPROXY_HTTP_FRONTEND _ROUTING_ONLY_WITH_AUT`	Works in combination with the HAPROXY_HTTP_FRONTEND_ACL_ONLY setting to map the access control list name to the appropriate backend and to add HTTP Basic authentication. The default template for `HAPROXY_HTTP_FRONTEND_ROUTING_ONLY_WITH_AUTH` is: `acl auth_{cleanedUpHostname} http_auth(user_{backend}) http-request auth realm “{realm}” if host_{cleanedUpHostname} !auth_{cleanedUpHostname} use_backend {backend} if host_{cleanedUpHostname}` You can override this template with the following app label for the first port (`0`) of a given app: `“HAPROXY_0_HTTP_FRONTEND_ROUTING_ONLY_WITH_AUTH”: " acl auth_{cleanedUpHostname} http_auth(user_{backend})\n http-request auth realm “{realm}” if host_{cleanedUpHostname} !auth_{cleanedUpHostname}\n use_backend {backend} if host_{cleanedUpHostname}\n"`
`HAPROXY_HTTP_FRONTEND _ROUTING_ONLY_WITH_PATH`	Works in combination with the HAPROXY_HTTP_FRONTEND_ACL_ONLY_WITH_PATH setting to map access control list (ACL) names to the appropriate backend. The default template for `HAPROXY_HTTP_FRONTEND_ROUTING_ONLY_WITH_PATH` is: `use_backend {backend} if host_{cleanedUpHostname} path_{backend}` You can override this template with the following app label for the first port (`0`) of a given app: `“HAPROXY_0_HTTP_FRONTEND_ROUTING_ONLY_WITH_PATH”: " use_backend {backend} if host_{cleanedUpHostname} path_{backend}\n"`
`HAPROXY_HTTP_FRONTEND _ROUTING_ONLY_WITH _PATH_AND_AUTH`	Works in combination with the HAPROXY_HTTP_FRONTEND_ACL_ONLY_WITH_PATH setting to map access control list names to the appropriate backend. The default template for `HAPROXY_HTTP_FRONTEND_ROUTING_ONLY_WITH_PATH_AND_AUTH` is: `http-request auth realm “{realm}” if host_{cleanedUpHostname} path_{backend} !auth_{cleanedUpHostname} use_backend {backend} if host_{cleanedUpHostname} path_{backend}` You can override this template with the following app label for the first port (`0`) of a given app: `“HAPROXY_0_HTTP_FRONTEND_ROUTING_ONLY_WITH_PATH_AND_AUTH”: " http-request auth realm “{realm}” if host_{cleanedUpHostname} path_{backend} !auth_{cleanedUpHostname}\n use_backend {backend} if host_{cleanedUpHostname} path_{backend}\n"`
`HAPROXY_MAP_HTTPS _FRONTEND_ACL`	Specifies the access control list (ACL) that performs the SNI-based host name matching for the HAPROXY_HTTPS_FRONTEND_HEAD template using HAProxy maps. The default template for `HAPROXY_MAP_HTTPS_FRONTEND_ACL` is: `use_backend %[ssl_fc_sni,lower,map({haproxy_dir}/domain2backend.map)` You can override this template with the following app label for the first port (`0`) of a given app: `“HAPROXY_0_MAP_HTTPS_FRONTEND_ACL”: " use_backend %[ssl_fc_sni,lower,map({haproxy_dir}/domain2backend.map)]\n"`
`HAPROXY_MAP_HTTP _FRONTEND_ACL`	Specifies the access control list (ACL) that glues a backend to the corresponding virtual host specified by the HAPROXY_HTTP_FRONTEND_HEAD setting using HAProxy maps. The default template for `HAPROXY_MAP_HTTP_FRONTEND_ACL` is: `use_backend %[req.hdr(host),lower,regsub(:.$,),map({haproxy_dir}/domain2backend.map)` You can override this template with the following app label for the first port (`0`) of a given app: `“HAPROXY_0_MAP_HTTP_FRONTEND_ACL”: " use_backend %[req.hdr(host),lower,regsub(:.$,),map({haproxy_dir}/domain2backend.map)]\n"`
`HAPROXY_MAP_HTTP _FRONTEND_ACL_ONLY`	Defines the access control list (ACL) that matches a particular host name, You should only use this template if you have multiple virtual hosts routing to the same backend in the HAProxy map. The default template for `HAPROXY_MAP_HTTP_FRONTEND_ACL_ONLY` is: `use_backend %[req.hdr(host),lower,regsub(:.$,),map({haproxy_dir}/domain2backend.map)` You can override this template with the following app label for the first port (`0`) of a given app: `“HAPROXY_0_MAP_HTTP_FRONTEND_ACL_ONLY”: " use_backend %[req.hdr(host),lower,regsub(:.$,),map({haproxy_dir}/domain2backend.map)]\n"`
`HAPROXY_MAP_HTTP _FRONTEND_APPID_ACL`	Specifies the access control list (ACL) that glues a backend to the corresponding app specified by the HAPROXY_HTTP_FRONTEND_APPID_HEAD setting using HAProxy maps. The default template for `HAPROXY_MAP_HTTP_FRONTEND_APPID_ACL` is: `use_backend %[req.hdr(x-marathon-app-id),lower,map({haproxy_dir}/app2backend.map)` You can override this template with the following app label for the first port (`0`) of a given app: `“HAPROXY_0_MAP_HTTP_FRONTEND_APPID_ACL”: " use_backend %[req.hdr(x-marathon-app-id),lower,map({haproxy_dir}/app2backend.map)]\n"`

User authentication list setting

Use the following template and app label to configure basic user name and password settings for the load balancer.

Template name Description and examples

Template name	Description and examples
`HAPROXY_USERLIST_HEAD`	Specifies the user list for HTTP Basic authentication. The default template for `HAPROXY_USERLIST_HEAD` is: `userlist user_{backend} user {user} password {passwd}` You can override this template with the following app label for the first port (`0`) of a given app: `“HAPROXY_0_USERLIST_HEAD”: “\nuserlist user_{backend}\n user {user} password {passwd}\n”`

HAPROXY_USERLIST_HEAD

Specifies the user list for HTTP Basic authentication.

The default template for HAPROXY_USERLIST_HEAD is: userlist user_{backend} user {user} password {passwd}

You can override this template with the following app label for the first port (0) of a given app: “HAPROXY_0_USERLIST_HEAD”: “\nuserlist user_{backend}\n user {user} password {passwd}\n”

Use the following template to configure default header settings for the load balancer.