Features

The following list provides a list of features supported by fabio.

Check out fabio.properties for a full list of config options.

Access Logging

1.4.1

fabio has support for writing access logs for HTTP requests. By default, access logs are disabled. To enable them set log.access.target=stdout. This will write access logs in the Common Log Format to stdout. The standard fabio logs are still written to stderr.

The log format can be controlled with the log.access.format parameter which is either common, combined - which outputs the Combined Log Format - or a custom format string which is fully described in fabio.properties.

Certificate Stores

1.2

fabio has support for dynamic certificate stores which allow you to store or issue certificates in a central place and update them at runtime without restarting fabio. You can store certificates in files, directories, on HTTP servers in Consul or in Vault.

See Certificate Stores for more detail.

Compression

1.3.4

To enable dynamic compression of responses when the client sets the Accept-Encoding: gzip header configure the proxy.gzip.contenttype property with a regular expression of the content types for which compression should be enabled.

Docker Support

1.0.0

To run fabio within Docker use the official Docker image and mount your own config file to /etc/fabio/fabio.properties

docker run -d -p 9999:9999 -p 9998:9998 -v $PWD/fabio/fabio.properties:/etc/fabio/fabio.properties fabiolb/fabio

If you want to run the Docker image with one or more SSL certificates then you can store your configuration and certificates in /etc/fabio and mount the entire directory, e.g.

$ cat ~/fabio/fabio.properties
proxy.addr=:443;/etc/fabio/ssl/mycert.pem;/etc/fabio/ssl/mykey.pem

docker run -d -p 443:443 -p 9998:9998 -v $PWD/fabio:/etc/fabio fabiolb/fabio

The official Docker image contains the root CA certificates from a recent and updated Ubuntu 12.04.5 LTS installation.

Registrator

If you use Gliderlabs Registrator to register your services you can pass the urlprefix- tags via the SERVICE_TAGS environment variable as follows:

$ docker run -d \
    --name=registrator \
    --net=host \        
    --volume=/var/run/docker.sock:/tmp/docker.sock \
    gliderlabs/registrator:latest \
    consul://localhost:8500

$ docker run -d -p 80:8000 \
    -e SERVICE_8000_CHECK_HTTP=/foo/healthcheck  \
    -e SERVICE_8000_NAME=foo \
    -e SERVICE_CHECK_INTERVAL=10s \
    -e SERVICE_CHECK_TIMEOUT=5s  \
    -e SERVICE_TAGS=urlprefix-/foo \
    test/foo

Docker Compose

If you are using Docker compose you can add the SERVICE_TAGS to the environment section as follows:

bar:
  environment:
    - SERVICE_TAGS=urlprefix-/bar

Dynamic Reloading

1.0.0

fabio watches services in consul and reloads its configuration on every change without interrupting existing connections.

Graceful Shutdown

1.0.0

fabio supports a graceful shutdown timeout during which new requests will receive a 503 Service Unavailable response while the active requests can complete. See the proxy.shutdownwait option in the fabio.properties file.

HTTP Header Support

1.1.3

In addition, to injecting the Forwarded and X-Real-Ip headers the X-Forwarded-For, X-Forwarded-Port and X-Forwarded-Proto headers are added to HTTP(S) and Websocket requests. Custom headers for the ip address and protocol can be configured with the proxy.header.clientip, proxy.header.tls and proxy.header.tls.value options.

HTTPS Upstream Support

1.4.2 (master)

To support HTTPS upstream servers add the proto=https option to the urlprefix- tag. The current implementation requires that upstream certificates need to be in the system root CA list. To disable certificate validation for a target set the tlsskipverify=true option.

urlprefix-/foo proto=https
urlprefix-/foo proto=https tlsskipverify=true

Metrics Support

1.0.0 (Graphite), 1.2.1 (StatsD/DataDog), >1.2.1 (Circonus)

fabio collects metrics per route and service instance as well as running totals to avoid computing large amounts of metrics. The metrics can be send to Circonus, Graphite, StatsD, DataDog (via statsd) or stdout. See the metrics.* options in the fabio.properties file.

Fabio reports the following metrics:

Name	Type	Description
{route}.rx	timer	Number of bytes received by fabion for TCP target
{route}.tx	timer	Number of bytes transmitted by fabio for TCP target
{route}	timer	Average response time for a route
http.status.code.{code}	timer	Average response time for all HTTP(S) requests per status code
notfound	counter	Number of failed HTTP route lookups
requests	timer	Average response time for all HTTP(S) requests
tcp.conn	counter	Number of established TCP proxy connections
tcp.connfail	counter	Number of TCP upstream connection failures
tcp.noroute	counter	Number of failed TCP upstream route lookups
tcp_sni.conn	counter	Number of established TCP+SNI proxy connections
tcp_sni.connfail	counter	Number of failed TCP+SNI proxy connections
tcp_sni.noroute	counter	Number of failed TCP+SNI upstream route lookups
ws.conn	gauge	Number of actively open websocket connections

Legend

timer

A timer counts events and provides an average throughput and latency number. Depending on the metrics provider the aggregation happens either in the metrics library (go-metrics: statsd, graphite) or in the system of the metrics provider (Circonus)

counter

A counter counts events and provides an monotonically increasing value.

gauge

A gauge provides a current value.

{code}

{code} is the three digit HTTP status code like 200.

{route}

{route} is a shorthand for the metrics name generated for a route with the metrics.names template defined in fabio.properties

Path Stripping

1.3.7

fabio supports stripping a path from the incoming request. If you want to forward http://host/foo/bar as http://host/bar you can add a strip=/foo option to the route options as urlprefix-/foo/bar strip=/foo.

PROXY Protocol Support

1.1.3

fabio transparently supports the HA Proxy PROXY protocol version 1 which is used by HA Proxy, Amazon ELB and others to transmit the remote address and port of the client without using headers.

SSE - Server-Sent Events

1.3

fabio detects SSE connections if the Accept header is set to text/event-stream and enables automatic flushing of the response buffer to forward data to the client. The default is set to 1s and can be configured with the proxy.flushinterval parameter.

TCP Proxy Support

1.4 (⭐️ new feature)

fabio can run a transparent TCP proxy which dynamically forwards an incoming connection on a given port to services which advertise that port. To use TCP proxy support the service needs to advertise urlprefix-:1234 proto=tcp in Consul. In addition, fabio needs to be configured to listen on that port:

fabio -proxy.addr ':1234;proto=tcp'

TCP proxy support can be combined with Certificate Stores to provide TLS termination on fabio.

fabio -proxy.cs 'cs=ssl;type=path;path=/etc/ssl' -proxy.addr ':1234;proto=tcp;cs=ssl'

TCP+SNI Proxy Support

1.3

fabio can run a transparent TCP proxy with SNI support which can forward any TLS connection without re-encrypting the traffic. fabio captures the ClientHello packet which is the first packet of the TLS handshake and extracts the server name from the SNI extension and uses it for finding the upstream server to forward the connection to. It then replays the ClientHello packet and then transparently forwards all traffic between client and server as a byte stream.

To enable this feature configure a listener as follows:

fabio -proxy.addr=':443;proto=tcp+sni'

to listen to more than 1 port separate with comma's (like if you want to do tcp and http listening):

fabio -proxy.addr ':9999,:19587;proto=tcp

This will do normal fabio http(s) routing on port 9999 and TCP proxy on port 19587.

and register your services in Consul with a urlprefix- tag that matches the host from the SNI extension. If your server responds to https://foo.com/... then you should register a urlprefix-foo.com/ tag for this service. Note that the tag should only contain <host>/ since path-based routing is not possible with this approach.

Traffic Shaping

1.0.0

fabio allows to control the amount of traffic a set of service instances will receive. You can use this feature to direct a fixed percentage of traffic to a newer version of an existing service for testing ("Canary testing"). See Manual Overrides for a complete description of the route weight command.

The following command will allocate 5% of traffic to www.kjca.dev/auth/ to all instances of service-b which match tags version-15 and dc-fra. This is independent of the number of actual instances running. The remaining 95% of the traffic will be distributed evenly across the remaining instances publishing the same prefix.

route weight service-b www.kjca.dev/auth/ weight 0.05 tags "version-15,dc-fra"

Request Debugging

1.0.0

To send a request from the command line via the fabio using curl you should send it as follows:

curl -v -H 'Host: foo.com' 'http://localhost:9999/path'

The -x or --proxy options will most likely not work as you expect as they send the full URL instead of just the request URI which usually does not match any route but the default one - if configured.

Request Tracing

1.0.0

To trace how a request is routed you can add a Trace header with an non- empty value which is truncated at 16 characters to keep the log output short.

$ curl -v -H 'Trace: abc' -H 'Host: foo.com' 'http://localhost:9999/bar/baz'

2015/09/28 21:56:26 [TRACE] abc Tracing foo.com/bar/baz
2015/09/28 21:56:26 [TRACE] abc No match foo.com/bang
2015/09/28 21:56:26 [TRACE] abc Match foo.com/
2015/09/28 22:01:34 [TRACE] abc Routing to http://1.2.3.4:8080/

Vault Integration

1.2, 1.6.0

fabio can use Vault as a secure key/value store to store certificates. As of 1.6.0 fabio can use the PKI support of Vault to generate TLS certificates on demand. See fabio.properties and the wiki for details.

Websocket Support

1.0.5

fabio transparently supports Websocket connections by detecting the Upgrade: websocket header in the incoming HTTP(S) request. See Websockets for more details.

Web UI

1.0.0

fabio supports a Web UI to examine the current routing table and manage the manual overrides. By default it listens on http://0.0.0.0:9998/ which can be changed with the ui.addr option. The ui.title and ui.color options allow customization of the title and the color of the header bar.