centauri

README

Centauri

Centauri is a TLS-terminating reverse-HTTP proxy written in Go.

Current status

Centauri is currently in development. There may be breaking changes as it evovles. Individual builds should be usable for production purposes, but you might want to keep another more established proxy around as a backup just in case.

Features

Automatic TLS certificates and OCSP stapling

Centauri will obtain TLS certificates from an ACME provider such as Let's Encrypt. It will keep these up to date, and ensure each one has a valid OCSP staple that can be sent to clients.

Centauri runs with sensible defaults for establishing TLS connections, in line with Mozilla's Intermediate recommendations. This balances security with accessibility for older clients.

Simple route configuration

Centauri's route configuration looks like this:

route www.example.com example.com
    upstream server1.internal.example.com:8080

route www.example.net
    upstream server1.internal.example.com:8080

You don't need to configure separate front-ends or back-ends, or deal with proxy_pass instructions.

Configuration

Centauri's behaviour is configured by environment vars. The following options are available:

• HTTP_PORT - port to listen on for non-TLS connections. These are automatically redirected to https. Default: 8080.
• HTTPS_PORT - port to listen on for TLS connections. Default: 8443.
• CONFIG - path to the route configuration (see below). Default: centauri.conf.
• USER_DATA - path to the file to store ACME user data in. Default: user.pem.
• CERTIFICATE_STORE - path to the file to store certificates in. Default: certs.json
• DNS_PROVIDER - the name of the DNS provider to use for ACME DNS-01 challenges. See below.
• ACME_EMAIL - the e-mail address to supply to the ACME server when registering.
• ACME_DIRECTORY - the URL of the ACME directory to obtain certs from. Default: https://acme-v02.api.letsencrypt.org/directory
• WILDCARD_DOMAINS - space separated list of domains that should use a wildcard certificate instead of listing individual subdomains. See below.

ACME DNS Configuration

In order to support wildcard domains, Centauri uses the DNS-01 challenge when proving ownership of domains. The DNS_PROVIDER env var must be set to one of the providers supported by Lego, and any credentials required for that provider must be specified in the relevant environment variables.

For example to configure Centauri to use the httpreq provider:

DNS_PROVIDER: httpreq
HTTPREQ_ENDPOINT: https://httpreq.example.com/
HTTPREQ_USERNAME: dade
HTTPREQ_PASSWORD: h4ck_7h3_p14n37

Wildcard domains

If you put a domain such as example.com in the WILDCARD_DOMAINS list, whenever a route needs a certificate for anything.example.com Centauri will instead replace it with *.example.com.

For example, a route with names example.com test.example.com and admin.example.com will result in a certificate issued for example.com *.example.com. This can be useful if you have a lot of different subdomains, or you don't want a particular subdomain exposed in certificate information.

Note that only one level of wildcard is supported: a wildcard certificate for *.example.com won't match foo.bar.example.com, nor will it match example.com.

Route configuration

To tell Centauri how it should route requests, you need to supply it with a route configuration file. This has a simple line-by-line format with the following directives:

• route - defines a route with a list of domain names that will be accepted from clients
• upstream - provides the hostname/IP and port of the upstream server the request will be proxied to
• header add - sets a header on all responses to the client, adding it to any issued by upstream.
• header replace - sets a header on all responses to the client, replacing any with the same name issued by upstream.
• header default - sets a header on all response to the client, only if upstream has not set the same header.
• header delete - removes a header from all responses to the client.

Lines that are empty or start with a # character are ignored, as is any whitespace at the start or end of lines. It is recommended to indent each route for readability, but it is entirely option.

A full route config may look something like this:

route example.com www.example.com
    upstream server1:8080
    header delete server
    header default Strict-Transport-Security max-age=15768000  
    header add X-Via Centauri

route example.net
    upstream server1:8081
    header replace Content-Security-Policy default-src 'self';

Feedback / Contributing

Feedback, feature requests, bug reports and pull requests are all welcome!