Certificate Stores

Starting with version 1.2 fabio has support for dynamic certificate stores which allow you to store certificates in a central place and update them at runtime without restarting fabio. As of Go <= 1.7 only TLS certificates can be changed at runtime. For updating client auth certificates golang issue 16066 is open.

Certificate stores are configured with the proxy.cs option. You can configure one or multiple stores.

Each certificate source is configured with a list of key/value options.

cs=<name>;type=<type>;opt=arg;opt[=arg];...

Each source must have a unique name which is then referenced in a listener configuration.

proxy.cs = cs=mycerts;type=...
proxy.addr = 1.2.3.4:9999;cs=mycerts;...

All certificates must be provided in PEM format

The following types of certificate sources are available:

• file: legacy store for a single TLS and a set of client auth certificates
• path: load certificates from a directory (e.g. managed by puppet/chef/ansible/...)
• http: load certificates from an HTTP server
• consul : load certificates from Consul KV store
• vault : load certificates from Vault

All certificate stores offer a set of common options. If you want to use client certificate authentication with an Amazon API gateway check the caupgcn option there.

At the end you also find a list of examples.

File

The file certificate source supports one certificate which is loaded at startup and is cached until the service exits.

The cert option contains the path to the certificate file. The key option contains the path to the private key file. If the certificate file contains both the certificate and the private key the key option can be omitted. The clientca option contains the path to one or more client authentication certificates.

Example

cs=<name>;type=file;cert=p/a-cert.pem;key=p/a-key.pem;clientca=p/clientAuth.pem

Path

The path certificate source loads certificates from a directory in alphabetical order and refreshes them periodically.

The cert option provides the path to the TLS certificates and the clientca option provides the path to the certificates for client authentication.

TLS certificates are stored either in one or two files:

www.example.com.pem or www.example.com-{cert,key}.pem

TLS certificates are loaded in alphabetical order and the first certificate is the default for clients which do not support SNI.

The refresh option can be set to specify the refresh interval for the TLS certificates. Client authentication certificates cannot be refreshed since Go does not provide a mechanism for that yet.

The default refresh interval is 3 seconds and cannot be lower than 1 second to prevent busy loops. To load the certificates only once and disable automatic refreshing set refresh to zero.

Example

cs=<name>;type=path;cert=path/to/certs;clientca=path/to/clientcas;refresh=3s

HTTP

The http certificate source loads certificates from an HTTP/HTTPS server.

The cert option provides a URL to a text file which contains all files that should be loaded from this directory. The filenames follow the same rules as for the path source. The text file can be generated with:

ls -1 *.pem > list

The clientca option provides a URL for the client authentication certificates analogous to the cert option.

Authentication credentials can be provided in the URL as request parameter, as basic authentication parameters or through a header.

The refresh option can be set to specify the refresh interval for the TLS certificates. Client authentication certificates cannot be refreshed since Go does not provide a mechanism for that yet.

The default refresh interval is 3 seconds and cannot be lower than 1 second to prevent busy loops. To load the certificates only once and disable automatic refreshing set refresh to zero.

Example

cs=<name>;type=http;cert=https://host.com/path/to/cert/list&token=123
cs=<name>;type=http;cert=https://user:pass@host.com/path/to/cert/list
cs=<name>;type=http;cert=https://host.com/path/to/cert/list;hdr=Authorization: Bearer 1234

Consul

The consul certificate source loads certificates from Consul.

The cert option provides a KV store URL where the the TLS certificates are stored.

The clientca option provides a URL to a path in the KV store where the the client authentication certificates are stored.

The filenames follow the same rules as for the path source.

The TLS certificates are updated automatically whenever the KV store changes. The client authentication certificates cannot be updated automatically since Go does not provide a mechanism for that yet. (See golang issue 16066)

Example

cs=<name>;type=consul;cert=http://localhost:8500/v1/kv/path/to/cert&token=123

Vault KV

The Vault KV certificate store uses HashiCorp Vault's KV secrets engine as the certificate store.

The cert option provides the path to the TLS certificates and the clientca option provides the path to the certificates for client authentication.

The refresh option can be set to specify the refresh interval for the TLS certificates. Client authentication certificates cannot be refreshed since Go does not provide a mechanism for that yet.

Certificate has to be stored in value. It means you have to write your cert into a cert and key fields of secret, that has to be your domain name.

Example:

vault write secret/fabio/certs/www.domain.com cert=@cert.pem key=@key.pem

The path to vault must be provided in the VAULT_ADDR environment variable. The token must be provided in the VAULT_TOKEN environment variable.

If you're running Vault with SSL, then you will also need to ensure that your CA's certificate is accessible to Fabio, and then set the VAULT_CAPATH environment variable to its path, i.e. /etc/ssl/vault/ca.pem.

fabio versions <= 1.2.1 require a token with root and/or sudo privileges to create an orphan token for itself. This required fabio to have more privileges than it needs and it also prevented revoking the fabio token if the parent token was revoked. Therefore, supplying a token with root and/or sudo privileges is now deprecated and will be removed in a later release.

fabio versions > 1.2.1 will no longer attempt to create a token itself and instead solely rely on the provided token. The provided token can be an orphan and should be renewable for the duration fabio is expected to run. It is recommended not to set the explicit_max_ttl unless fabio is restarted before that time expires.

The KV store requires the following minimal policy:

# KV Version 1
path "secret/fabio/certs/" {
  capabilities = ["list"]
}
path "secret/fabio/certs/*" {
  capabilities = ["read"]
}

# KV Version 2
path "secret/metadata/fabio/certs/" {
  capabilities = ["list"]
}
path "secret/data/fabio/certs/*" {
  capabilities = ["read"]
}

# The following capabilities are typically provided by Vault's default policy.
path "auth/token/lookup-self" {
    capabilities = ["read"]                
}                   
path "auth/token/renew-self" {
    capabilities = ["update"]                                        
}                         

See the Vault documentation for differences between the KV versions.

Example

cs=<name>;type=vault;cert=secret/fabio/certs

Vault PKI

The Vault PKI certificate store uses HashiCorp Vault to issue certificates on demand.

The cert option provides the path to an issue endpoint in a PKI secrets engine. The clientca option works the same as for the Vault KV store (see above).

The 'refresh' option determines how long before the expiration date certificates are re-issued. Values smaller than one hour are silently changed to one hour, which is also the default.

As with the Vault KV store, the VAULT_ADDR and VAULT_TOKEN environment variables are used to configure the Vault address and token, respectively, and fabio will attempt to renew the token as necessary. Consider using an orphaned token without an explicit_max_ttl if fabio is expected to run more than the maximum TTL for Vault tokens (typically around 30 days).

Example

cs=<name>;type=vault-pki;cert=pki/issue/example-dot-com

With this configuration fabio will use the example-dot-com role to issue certificates. Naturally the example-dot-com must allow issuing certificates for every common name that fabio is expected to receive requests for.

Note that requests for pki/issue/example-dot-com are update requests, not read requests. The minimal policy that fabio requires is therefore

path "pki/issue/example-dot-com" {
  capabilities = ["update"]
}

# The following capabilities are typically provided by Vault's default policy.
path "auth/token/lookup-self" {
    capabilities = ["read"]                
}                   
path "auth/token/renew-self" {
    capabilities = ["update"]                                        
}                         

Refer to Vault's PKI documentation for details on how to configure the PKI mount and role.

Common options

All certificate stores support the following options:

• caupgcn : Upgrade a self-signed client auth certificate with this common-name to a CA certificate. Typically used for self-singed certificates for the Amazon AWS API Gateway certificates which do not have the CA flag set which makes them unsuitable for client certificate authentication in Go. For the AWS API Gateway set this value to 'ApiGateway' to allow client certificate authentication. This replaces the deprecated parameter 'aws.apigw.cert.cn' which was introduced in version 1.1.5.

Examples

 # file based certificate source
 proxy.cs = cs=some-name;type=file;cert=p/a-cert.pem;key=p/a-key.pem

 # path based certificate source
 proxy.cs = cs=some-name;type=path;cert=path/to/certs

 # HTTP certificate source
 proxy.cs = cs=some-name;type=http;cert=https://user:pass@host:port/path/to/certs

 # Consul certificate source
 proxy.cs = cs=some-name;type=consul;cert=https://host:port/v1/kv/path/to/certs?token=abc123

 # Vault certificate source
 proxy.cs = cs=some-name;type=vault;cert=secret/fabio/certs

 # Multiple certificate sources
 proxy.cs = cs=srcA;type=path;cert=path/to/certs,\
            cs=srcB;type=http;cert=https://user:pass@host:port/path/to/certs

 # path based certificate source for AWS Api Gateway
 proxy.cs = cs=some-name;type=path;cert=path/to/certs;clientca=path/to/clientcas;caupgcn=ApiGateway