From 1ab9c82dfb7b3de8b53340ac12f78871083e26d7 Mon Sep 17 00:00:00 2001 From: Emile Vauge Date: Tue, 15 Mar 2016 16:50:14 +0100 Subject: [PATCH] Let's Encrypt Doc Signed-off-by: Emile Vauge --- README.md | 9 ++- docs/index.md | 175 ++++++++++++++++++++++++++++++++++++++++++-- traefik.sample.toml | 57 +++++++++++++++ 3 files changed, 231 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 6b826fdef..829aa61e5 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@

[![Build Status](https://travis-ci.org/containous/traefik.svg?branch=master)](https://travis-ci.org/containous/traefik) -[![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](https://github.com/containous/traefik/blob/master/LICENSE.md) +[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/containous/traefik/blob/master/LICENSE.md) [![Join the chat at https://traefik.herokuapp.com](https://img.shields.io/badge/style-register-green.svg?style=social&label=Slack)](https://traefik.herokuapp.com) [![Twitter](https://img.shields.io/twitter/follow/traefikproxy.svg?style=social)](https://twitter.com/intent/follow?screen_name=traefikproxy) @@ -18,8 +18,7 @@ It supports several backends ([Docker :whale:](https://www.docker.com/), [Mesos/ - [It's fast](docs/index.md#benchmarks) - No dependency hell, single binary made with go -- Simple json Rest API -- Simple TOML file configuration +- Rest API - Multiple backends supported: Docker, Mesos/Marathon, Consul, Etcd, and more to come - Watchers for backends, can listen change in backends to apply a new configuration automatically - Hot-reloading of configuration. No need to restart the process @@ -29,10 +28,11 @@ It supports several backends ([Docker :whale:](https://www.docker.com/), [Mesos/ - Rest Metrics - Tiny docker image included [![Image Layers](https://badge.imagelayers.io/containous/traefik:latest.svg)](https://imagelayers.io/?images=containous/traefik:latest) - SSL backends support -- SSL frontend support +- SSL frontend support (with SNI) - Clean AngularJS Web UI - Websocket support - HTTP/2 support +- [Let's Encrypt](https://letsencrypt.org) support (Automatic HTTPS) ## Demo @@ -53,6 +53,7 @@ You can access to a simple HTML frontend of Træfik. - [Gorilla mux](https://github.com/gorilla/mux): famous request router - [Negroni](https://github.com/codegangsta/negroni): web middlewares made simple - [Manners](https://github.com/mailgun/manners): graceful shutdown of http.Handler servers +- [Lego](https://github.com/xenolf/lego): the best [Let's Encrypt](https://letsencrypt.org) library in go ## Quick start diff --git a/docs/index.md b/docs/index.md index 8e13b1643..55fe6eb8a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,6 +1,6 @@ -![Træfɪk](http://traefik.github.io/traefik.logo.svg "Træfɪk") -___ - +

+Træfɪk +

# Documentation @@ -54,15 +54,20 @@ Various methods of load-balancing is supported: - `drr`: Dynamic Round Robin: increases weights on servers that perform better than others. It also rolls back to original weights if the servers have changed. A circuit breaker can also be applied to a backend, preventing high loads on failing servers. +Initial state is Standby. CB observes the statistics and does not modify the request. +In case if condition matches, CB enters Tripped state, where it responds with predefines code or redirects to another frontend. +Once Tripped timer expires, CB enters Recovering state and resets all stats. +In case if the condition does not match and recovery timer expries, CB enters Standby state. + It can be configured using: - Methods: `LatencyAtQuantileMS`, `NetworkErrorRatio`, `ResponseCodeRatio` - Operators: `AND`, `OR`, `EQ`, `NEQ`, `LT`, `LE`, `GT`, `GE` For example: -- `NetworkErrorRatio() > 0.5` -- `LatencyAtQuantileMS(50.0) > 50` -- `ResponseCodeRatio(500, 600, 0, 600) > 0.5` +- `NetworkErrorRatio() > 0.5`: watch error ratio over 10 second sliding window for a frontend +- `LatencyAtQuantileMS(50.0) > 50`: watch latency at quantile in milliseconds. +- `ResponseCodeRatio(500, 600, 0, 600) > 0.5`: ratio of response codes in range [500-600) to [0-600) ## Launch configuration @@ -230,6 +235,65 @@ Use "traefik [command] --help" for more information about a command. # # defaultEntryPoints = ["http", "https"] +# Enable ACME (Let's Encrypt): automatic SSL +# +# Optional +# +# [acme] + +# Email address used for registration +# +# Required +# +# email = "test@traefik.io" + +# File used for certificates storage. +# WARNING, if you use Traefik in Docker, don't forget to mount this file as a volume. +# +# Required +# +# storageFile = "acme.json" + +# Entrypoint to proxy acme challenge to. +# WARNING, must point to an entrypoint on port 80 +# +# Required +# +# entryPoint = "http" + +# Enable on demand certificate. This will request a certificate from Let's Encrypt during the first TLS handshake for a hostname that does not yet have a certificate. +# WARNING, TLS handshakes will be slow when requesting a hostname certificate for the first time, this can leads to DoS attacks. +# WARNING, Take note that Let's Encrypt have rate limiting: https://community.letsencrypt.org/t/quick-start-guide/1631 +# +# Optional +# +# onDemand = true + +# CA server to use +# Uncomment the line to run on the staging let's encrypt server +# Leave comment to go to prod +# +# Optional +# +# caServer = "https://acme-staging.api.letsencrypt.org/directory" + +# Domains list +# You can provide SANs (alternative domains) to each main domain +# WARNING, Take note that Let's Encrypt have rate limiting: https://community.letsencrypt.org/t/quick-start-guide/1631 +# Each domain & SANs will lead to a certificate request. +# +# [[acme.domains]] +# main = "local1.com" +# sans = ["test1.local1.com", "test2.local1.com"] +# [[acme.domains]] +# main = "local2.com" +# sans = ["test1.local2.com", "test2x.local2.com"] +# [[acme.domains]] +# main = "local3.com" +# [[acme.domains]] +# main = "local4.com" + + # Entrypoints definition # # Optional @@ -263,6 +327,105 @@ Use "traefik [command] --help" for more information about a command. # replacement = "http://mydomain/$1" ``` +### Samples + +#### HTTP only + +``` +defaultEntryPoints = ["http"] +[entryPoints] + [entryPoints.http] + address = ":80" +``` + +### HTTP + HTTPS (with SNI) + +``` +defaultEntryPoints = ["http", "https"] +[entryPoints] + [entryPoints.http] + address = ":80" + [entryPoints.https] + address = ":443" + [entryPoints.https.tls] + [[entryPoints.https.tls.certificates]] + CertFile = "integration/fixtures/https/snitest.com.cert" + KeyFile = "integration/fixtures/https/snitest.com.key" + [[entryPoints.https.tls.certificates]] + CertFile = "integration/fixtures/https/snitest.org.cert" + KeyFile = "integration/fixtures/https/snitest.org.key" +``` + +### HTTP redirect on HTTPS + +``` +defaultEntryPoints = ["http", "https"] +[entryPoints] + [entryPoints.http] + address = ":80" + [entryPoints.http.redirect] + entryPoint = "https" + [entryPoints.https] + address = ":443" + [entryPoints.https.tls] + [[entryPoints.https.tls.certificates]] + certFile = "tests/traefik.crt" + keyFile = "tests/traefik.key" +``` + +### Let's Encrypt support + +``` +[entryPoints] + [entryPoints.http] + address = ":80" + [entryPoints.http.redirect] + entryPoint = "https" + [entryPoints.https] + address = ":443" + [entryPoints.https.tls] +[acme] +email = "test@traefik.io" +storageFile = "acme.json" +onDemand = true +caServer = "http://172.18.0.1:4000/directory" +entryPoint = "http" + +[[acme.domains]] + main = "local1.com" + sans = ["test1.local1.com", "test2.local1.com"] +[[acme.domains]] + main = "local2.com" + sans = ["test1.local2.com", "test2x.local2.com"] +[[acme.domains]] + main = "local3.com" +[[acme.domains]] + main = "local4.com" +``` + +### Override entrypoints in frontends + +``` +[frontends] + [frontends.frontend1] + backend = "backend2" + [frontends.frontend1.routes.test_1] + rule = "Host" + value = "test.localhost" + [frontends.frontend2] + backend = "backend1" + passHostHeader = true + entrypoints = ["https"] # overrides defaultEntryPoints + [frontends.frontend2.routes.test_1] + rule = "Host" + value = "{subdomain:[a-z]+}.localhost" + [frontends.frontend3] + entrypoints = ["http", "https"] # overrides defaultEntryPoints + backend = "backend2" + rule = "Path" + value = "/test" +``` + ## File backend diff --git a/traefik.sample.toml b/traefik.sample.toml index 27f6e822a..8766d495a 100644 --- a/traefik.sample.toml +++ b/traefik.sample.toml @@ -55,6 +55,63 @@ # # defaultEntryPoints = ["http", "https"] +# Enable ACME (Let's Encrypt): automatic SSL +# +# Optional +# +# [acme] + +# Email address used for registration +# +# Required +# +# email = "test@traefik.io" + +# File used for certificates storage. +# WARNING, if you use Traefik in Docker, don't forget to mount this file as a volume. +# +# Required +# +# storageFile = "acme.json" + +# Entrypoint to proxy acme challenge to. +# WARNING, must point to an entrypoint on port 80 +# +# Required +# +# entryPoint = "http" + +# Enable on demand certificate. This will request a certificate from Let's Encrypt during the first TLS handshake for a hostname that does not yet have a certificate. +# WARNING, TLS handshakes will be slow when requesting a hostname certificate for the first time, this can leads to DoS attacks. +# WARNING, Take note that Let's Encrypt have rate limiting: https://community.letsencrypt.org/t/quick-start-guide/1631 +# +# Optional +# +# onDemand = true + +# CA server to use +# Uncomment the line to run on the staging let's encrypt server +# Leave comment to go to prod +# +# Optional +# +# caServer = "https://acme-staging.api.letsencrypt.org/directory" + +# Domains list +# You can provide SANs (alternative domains) to each main domain +# +# [[acme.domains]] +# main = "local1.com" +# sans = ["test1.local1.com", "test2.local1.com"] +# [[acme.domains]] +# main = "local2.com" +# sans = ["test1.local2.com", "test2x.local2.com"] +# [[acme.domains]] +# main = "local3.com" +# [[acme.domains]] +# main = "local4.com" + + # Entrypoints definition # # Optional