homelab/traefik
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Documentation Revamp

Browse source 
Co-authored-by: jbdoumenjou <jb.doumenjou@gmail.com>
This commit is contained in:
Gérald Croës 2019-02-26 05:50:07 -08:00 • committed by Traefiker Bot
parent 848e45c22c
commit ac6b11037d
174 changed files with 5858 additions and 4002 deletions
Download patch file Download diff file Expand all files Collapse all files

330
docs/content/routing/acme.md Normal file
View file

@ -0,0 +1,330 @@
# ACME
Automatic HTTPS
{: .subtitle }
Traefik can automatically generate certificates for your domains using an ACME provider (like Let's Encrypt).
!!! warning "Let's Encrypt and Rate Limiting"
Note that Let's Encrypt has [rate limiting](https://letsencrypt.org/docs/rate-limits).
## Configuration Examples
??? example "Configuring ACME on the Https EntryPoint"
```toml
[entryPoints]
[entryPoints.web]
address = ":80"
[entryPoints.http-tls]
address = ":443"
[entryPoints.http-tls.tls] # enabling TLS
[acme]
email = "your-email@your-domain.org"
storage = "acme.json"
entryPoint = "http-tls" # acme is enabled on http-tls
onHostRule = true # dynamic generation based on the Host() matcher
[acme.httpChallenge]
entryPoint = "web" # used during the challenge
```
??? example "Configuring Wildcard Certificates"
```toml
[entryPoints]
[entryPoints.web]
address = ":80"
[entryPoints.http-tls]
address = ":443"
[entryPoints.https.tls] # enabling TLS
[acme]
email = "your-email@your-domain.org"
storage = "acme.json"
entryPoint = "http-tls" # acme is enabled on http-tls
[acme.dnsChallenge]
provider = "xxx"
[[acme.domains]]
main = "*.mydomain.com"
sans = ["mydomain.com"]
```
!!! note "Configuration Reference"
There are many available options for ACME. For a quick glance at what's possible, browse the [configuration reference](../reference/acme.md).
## Configuration Options
### The Different ACME Challenges
#### tlsChallenge
Use the `TLS-ALPN-01` challenge to generate and renew ACME certificates by provisioning a TLS certificate.
??? example "Using an EntryPoint Called https for the `tlsChallenge`"
```toml
[acme]
# ...
entryPoint = "https"
[acme.tlsChallenge]
```
!!! note
As described on the Let's Encrypt [community forum](https://community.letsencrypt.org/t/support-for-ports-other-than-80-and-443/3419/72), when using the `TLS-ALPN-01` challenge, `acme.entryPoint` must be reachable by Let's Encrypt through port 443.
#### `httpChallenge`
Use the `HTTP-01` challenge to generate and renew ACME certificates by provisioning an HTTP resource under a well-known URI.
??? example "Using an EntryPoint Called http for the `httpChallenge`"
```toml
[acme]
# ...
entryPoint = "https"
[acme.httpChallenge]
entryPoint = "http"
```
!!! note
As described on the Let's Encrypt [community forum](https://community.letsencrypt.org/t/support-for-ports-other-than-80-and-443/3419/72), when using the `HTTP-01` challenge, `acme.httpChallenge.entryPoint` must be reachable by Let's Encrypt through port 80.
!!! note
Redirection is fully compatible with the `HTTP-01` challenge.
#### `dnsChallenge`
Use the `DNS-01` challenge to generate and renew ACME certificates by provisioning a DNS record.
??? example "Configuring a `dnsChallenge` with the digitalocean Provider"
```toml
[acme]
# ...
[acme.dnsChallenge]
provider = "digitalocean"
delayBeforeCheck = 0
# ...
```
!!! important
A `provider` is mandatory.
??? list "Supported Providers"
Here is a list of supported `providers`, that can automate the DNS verification, along with the required environment variables and their [wildcard & root domain support](#wildcard-domains).
| Provider Name | Provider Code | Environment Variables | Wildcard & Root Domain Support |
|--------------------------------------------------------|----------------|-------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------|
| [ACME DNS](https://github.com/joohoi/acme-dns) | `acme-dns` | `ACME_DNS_API_BASE`, `ACME_DNS_STORAGE_PATH` | Not tested yet |
| [Alibaba Cloud](https://www.vultr.com) | `alidns` | `ALICLOUD_ACCESS_KEY`, `ALICLOUD_SECRET_KEY`, `ALICLOUD_REGION_ID` | Not tested yet |
| [Auroradns](https://www.pcextreme.com/aurora/dns) | `auroradns` | `AURORA_USER_ID`, `AURORA_KEY`, `AURORA_ENDPOINT` | Not tested yet |
| [Azure](https://azure.microsoft.com/services/dns/) | `azure` | `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, `AZURE_SUBSCRIPTION_ID`, `AZURE_TENANT_ID`, `AZURE_RESOURCE_GROUP`, `[AZURE_METADATA_ENDPOINT]` | Not tested yet |
| [Blue Cat](https://www.bluecatnetworks.com/) | `bluecat` | `BLUECAT_SERVER_URL`, `BLUECAT_USER_NAME`, `BLUECAT_PASSWORD`, `BLUECAT_CONFIG_NAME`, `BLUECAT_DNS_VIEW` | Not tested yet |
| [Cloudflare](https://www.cloudflare.com) | `cloudflare` | `CF_API_EMAIL`, `CF_API_KEY` - The `Global API Key` needs to be used, not the `Origin CA Key` | YES |
| [CloudXNS](https://www.cloudxns.net) | `cloudxns` | `CLOUDXNS_API_KEY`, `CLOUDXNS_SECRET_KEY` | Not tested yet |
| [ConoHa](https://www.conoha.jp) | `conoha` | `CONOHA_TENANT_ID`, `CONOHA_API_USERNAME`, `CONOHA_API_PASSWORD` | YES |
| [DigitalOcean](https://www.digitalocean.com) | `digitalocean` | `DO_AUTH_TOKEN` | YES |
| [DNSimple](https://dnsimple.com) | `dnsimple` | `DNSIMPLE_OAUTH_TOKEN`, `DNSIMPLE_BASE_URL` | Not tested yet |
| [DNS Made Easy](https://dnsmadeeasy.com) | `dnsmadeeasy` | `DNSMADEEASY_API_KEY`, `DNSMADEEASY_API_SECRET`, `DNSMADEEASY_SANDBOX` | Not tested yet |
| [DNSPod](https://www.dnspod.com/) | `dnspod` | `DNSPOD_API_KEY` | Not tested yet |
| [DreamHost](https://www.dreamhost.com/) | `dreamhost` | `DREAMHOST_API_KEY` | YES |
| [Duck DNS](https://www.duckdns.org/) | `duckdns` | `DUCKDNS_TOKEN` | No |
| [Dyn](https://dyn.com) | `dyn` | `DYN_CUSTOMER_NAME`, `DYN_USER_NAME`, `DYN_PASSWORD` | Not tested yet |
| External Program | `exec` | `EXEC_PATH` | YES |
| [Exoscale](https://www.exoscale.com) | `exoscale` | `EXOSCALE_API_KEY`, `EXOSCALE_API_SECRET`, `EXOSCALE_ENDPOINT` | YES |
| [Fast DNS](https://www.akamai.com/) | `fastdns` | `AKAMAI_CLIENT_TOKEN`, `AKAMAI_CLIENT_SECRET`, `AKAMAI_ACCESS_TOKEN` | Not tested yet |
| [Gandi](https://www.gandi.net) | `gandi` | `GANDI_API_KEY` | Not tested yet |
| [Gandi v5](http://doc.livedns.gandi.net) | `gandiv5` | `GANDIV5_API_KEY` | YES |
| [Glesys](https://glesys.com/) | `glesys` | `GLESYS_API_USER`, `GLESYS_API_KEY`, `GLESYS_DOMAIN` | Not tested yet |
| [GoDaddy](https://godaddy.com/domains) | `godaddy` | `GODADDY_API_KEY`, `GODADDY_API_SECRET` | Not tested yet |
| [Google Cloud DNS](https://cloud.google.com/dns/docs/) | `gcloud` | `GCE_PROJECT`, `GCE_SERVICE_ACCOUNT_FILE` | YES |
| [hosting.de](https://www.hosting.de) | `hostingde` | `HOSTINGDE_API_KEY`, `HOSTINGDE_ZONE_NAME` | Not tested yet |
| HTTP request | `httpreq` | `HTTPREQ_ENDPOINT`, `HTTPREQ_MODE`, `HTTPREQ_USERNAME`, `HTTPREQ_PASSWORD` (1) | YES |
| [IIJ](https://www.iij.ad.jp/) | `iij` | `IIJ_API_ACCESS_KEY`, `IIJ_API_SECRET_KEY`, `IIJ_DO_SERVICE_CODE` | Not tested yet |
| [INWX](https://www.inwx.de/en) | `inwx` | `INWX_USERNAME`, `INWX_PASSWORD` | YES |
| [Lightsail](https://aws.amazon.com/lightsail/) | `lightsail` | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `DNS_ZONE` | Not tested yet |
| [Linode](https://www.linode.com) | `linode` | `LINODE_API_KEY` | Not tested yet |
| [Linode v4](https://www.linode.com) | `linodev4` | `LINODE_TOKEN` | Not tested yet |
| manual | - | none, but you need to run Traefik interactively, turn on `acmeLogging` to see instructions and press <kbd>Enter</kbd>. | YES |
| [MyDNS.jp](https://www.mydns.jp/) | `mydnsjp` | `MYDNSJP_MASTER_ID`, `MYDNSJP_PASSWORD` | YES |
| [Namecheap](https://www.namecheap.com) | `namecheap` | `NAMECHEAP_API_USER`, `NAMECHEAP_API_KEY` | YES |
| [name.com](https://www.name.com/) | `namedotcom` | `NAMECOM_USERNAME`, `NAMECOM_API_TOKEN`, `NAMECOM_SERVER` | Not tested yet |
| [Netcup](https://www.netcup.eu/) | `netcup` | `NETCUP_CUSTOMER_NUMBER`, `NETCUP_API_KEY`, `NETCUP_API_PASSWORD` | Not tested yet |
| [NIFCloud](https://cloud.nifty.com/service/dns.htm) | `nifcloud` | `NIFCLOUD_ACCESS_KEY_ID`, `NIFCLOUD_SECRET_ACCESS_KEY` | Not tested yet |
| [Ns1](https://ns1.com/) | `ns1` | `NS1_API_KEY` | Not tested yet |
| [Open Telekom Cloud](https://cloud.telekom.de) | `otc` | `OTC_DOMAIN_NAME`, `OTC_USER_NAME`, `OTC_PASSWORD`, `OTC_PROJECT_NAME`, `OTC_IDENTITY_ENDPOINT` | Not tested yet |
| [OVH](https://www.ovh.com) | `ovh` | `OVH_ENDPOINT`, `OVH_APPLICATION_KEY`, `OVH_APPLICATION_SECRET`, `OVH_CONSUMER_KEY` | YES |
| [PowerDNS](https://www.powerdns.com) | `pdns` | `PDNS_API_KEY`, `PDNS_API_URL` | Not tested yet |
| [Rackspace](https://www.rackspace.com/cloud/dns) | `rackspace` | `RACKSPACE_USER`, `RACKSPACE_API_KEY` | Not tested yet |
| [RFC2136](https://tools.ietf.org/html/rfc2136) | `rfc2136` | `RFC2136_TSIG_KEY`, `RFC2136_TSIG_SECRET`, `RFC2136_TSIG_ALGORITHM`, `RFC2136_NAMESERVER` | Not tested yet |
| [Route 53](https://aws.amazon.com/route53/) | `route53` | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `[AWS_REGION]`, `[AWS_HOSTED_ZONE_ID]` or a configured user/instance IAM profile. | YES |
| [Sakura Cloud](https://cloud.sakura.ad.jp/) | `sakuracloud` | `SAKURACLOUD_ACCESS_TOKEN`, `SAKURACLOUD_ACCESS_TOKEN_SECRET` | Not tested yet |
| [Selectel](https://selectel.ru/en/) | `selectel` | `SELECTEL_API_TOKEN` | YES |
| [Stackpath](https://www.stackpath.com/) | `stackpath` | `STACKPATH_CLIENT_ID`, `STACKPATH_CLIENT_SECRET`, `STACKPATH_STACK_ID` | Not tested yet |
| [TransIP](https://www.transip.nl/) | `transip` | `TRANSIP_ACCOUNT_NAME`, `TRANSIP_PRIVATE_KEY_PATH` | YES |
| [VegaDNS](https://github.com/shupp/VegaDNS-API) | `vegadns` | `SECRET_VEGADNS_KEY`, `SECRET_VEGADNS_SECRET`, `VEGADNS_URL` | Not tested yet |
| [Vscale](https://vscale.io/) | `vscale` | `VSCALE_API_TOKEN` | YES |
| [VULTR](https://www.vultr.com) | `vultr` | `VULTR_API_KEY` | Not tested yet |
- (1): more information about the HTTP message format can be found [here](https://github.com/xenolf/lego/blob/master/providers/dns/httpreq/readme.md)
!!! note "`delayBeforeCheck`"
By default, the `provider` verifies the TXT record _before_ letting ACME verify.
You can delay this operation by specifying a delay (in seconds) with `delayBeforeCheck` (value must be greater than zero).
This option is useful when internal networks block external DNS queries.
!!! note "`resolvers`"
Use custom DNS servers to resolve the FQDN authority.
```toml
[acme]
# ...
[acme.dnsChallenge]
# ...
resolvers = ["1.1.1.1:53", "8.8.8.8:53"]
```
### Known Domains, SANs, and Wildcards
You can set SANs (alternative domains) for each main domain.
Every domain must have A/AAAA records pointing to Traefik.
Each domain & SAN will lead to a certificate request.
```toml
[acme]
# ...
[[acme.domains]]
main = "local1.com"
sans = ["test1.local1.com", "test2.local1.com"]
[[acme.domains]]
main = "local2.com"
[[acme.domains]]
main = "*.local3.com"
sans = ["local3.com", "test1.test1.local3.com"]
# ...
```
!!! important
The certificates for the domains listed in `acme.domains` are negotiated at Traefik startup only.
!!! note
Wildcard certificates can only be verified through a `DNS-01` challenge.
#### Wildcard Domains
[ACME V2](https://community.letsencrypt.org/t/acme-v2-and-wildcard-certificate-support-is-live/55579) supports wildcard certificates.
As described in [Let's Encrypt's post](https://community.letsencrypt.org/t/staging-endpoint-for-acme-v2/49605) wildcard certificates can only be generated through a [`DNS-01` challenge](#dnschallenge).
```toml
[acme]
# ...
[[acme.domains]]
main = "*.local1.com"
sans = ["local1.com"]
# ...
```
!!! note "Double Wildcard Certificates"
It is not possible to request a double wildcard certificate for a domain (for example `*.*.local.com`).
Due to an ACME limitation it is not possible to define wildcards in SANs (alternative domains).
Thus, the wildcard domain has to be defined as a main domain.
Most likely the root domain should receive a certificate too, so it needs to be specified as SAN and 2 `DNS-01` challenges are executed.
In this case the generated DNS TXT record for both domains is the same.
Even though this behavior is [DNS RFC](https://community.letsencrypt.org/t/wildcard-issuance-two-txt-records-for-the-same-name/54528/2) compliant, it can lead to problems as all DNS providers keep DNS records cached for a given time (TTL) and this TTL can be greater than the challenge timeout making the `DNS-01` challenge fail.
The Traefik ACME client library [LEGO](https://github.com/xenolf/lego) supports some but not all DNS providers to work around this issue.
The [Supported `provider` table](#dnschallenge) indicates if they allow generating certificates for a wildcard domain and its root domain.
### caServer
??? example "Using the Let's Encrypt staging server"
```toml
[acme]
# ...
caServer = "https://acme-staging-v02.api.letsencrypt.org/directory"
# ...
```
### onHostRule
Enable certificate generation on [routers](routers.md) `Host` rules (for routers active on the `acme.entryPoint`).
This will request a certificate from Let's Encrypt for each router with a Host rule.
```toml
[acme]
# ...
onHostRule = true
# ...
```
!!! note "Multiple Hosts in a Rule"
The rule `Host(test1.traefik.io,test2.traefik.io)` will request a certificate with the main domain `test1.traefik.io` and SAN `test2.traefik.io`.
!!! warning
`onHostRule` option can not be used to generate wildcard certificates. Refer to [wildcard generation](#wildcard-domains) for further information.
### `storage`
The `storage` option sets the location where your ACME certificates are saved to.
```toml
[acme]
# ...
storage = "acme.json"
# ...
```
The value can refer to two kinds of storage:
- a JSON file
- a KV store entry
#### In a File
ACME certificates can be stored in a JSON file that needs to have a `600` file mode .
In Docker you can mount either the JSON file, or the folder containing it:
```bash
docker run -v "/my/host/acme.json:acme.json" traefik
```
```bash
docker run -v "/my/host/acme:/etc/traefik/acme" traefik
```
!!! warning
For concurrency reason, this file cannot be shared across multiple instances of Traefik. Use a key value store entry instead.
#### In a a Key Value Store Entry
ACME certificates can be stored in a key-value store entry.
```toml
storage = "traefik/acme/account"
```
!!! note "Storage Size"
Because key-value stores have limited entry size, the certificates list is compressed _before_ it is saved.
For example, it is possible to store up to _approximately_ 100 ACME certificates in Consul.
## Fallbacks
If Let's Encrypt is not reachable, the following certificates will apply:
1. Previously generated ACME certificates (before downtime)
1. Expired ACME certificates
1. Provided certificates
!!! note
For new (sub)domains which need Let's Encrypt authentification, the default Traefik certificate will be used until Traefik is restarted.

301
docs/content/routing/entrypoints.md Normal file
View file

@ -0,0 +1,301 @@
# EntryPoints
Opening Connections for Incomming Requests
{: .subtitle }
![EntryPoints](../assets/img/entrypoints.png)
Entrypoints are the network entry points into Traefik.
They can be defined using:
- a port (80, 443, ...)
- SSL (Certificates, Keys, authentication with a client certificate signed by a trusted CA, ...)
## Configuration Examples
??? example "HTTP only"
```toml
[entryPoints]
[entryPoints.http]
address = ":80"
```
We define an `entrypoint` called `http` that will listen on port `80`.
??? example "HTTP & HTTPS"
```toml
[entryPoints]
[entryPoints.http]
address = ":80"
[entryPoints.https]
address = ":443"
[entryPoints.https.tls]
[[entryPoints.https.tls.certificates]]
certFile = "tests/traefik.crt"
keyFile = "tests/traefik.key"
```
- Two entrypoints are defined: one called `http`, and the other called `https`.
- `http` listens on port `80`, and `https` on port `443`.
- We enabled SSL on `https` by giving it a certificate and a key.
!!! note
In the example, `http` and `https` are the names for the entrypoints and have nothing to do with the underlying protocol.
We could have written `entryPoints.foo` and `entryPoints.bar` instead.
!!! tip "Automatic HTTPS with ACME"
If you don't have certificate files and wish to automatically enable HTTPS, you should have a look at one of Traefik's most praised feature: [ACME & Let's Encrypt integration](./acme.md)
??? example "Client Certificate Authentication"
```toml
[entryPoints]
[entryPoints.https]
address = ":443"
[entryPoints.https.tls]
[entryPoints.https.tls.ClientCA]
files = ["tests/clientca1.crt", "tests/clientca2.crt"]
optional = false
[[entryPoints.https.tls.certificates]]
certFile = "tests/traefik.crt"
keyFile = "tests/traefik.key"
```
- We enabled SSL on `https` by giving it a certificate and a key.
- Files containing Certificate Authorities (PEM format) were added.
!!! note "Multiple CAs"
It is possible to have multiple CA:s in the same file or keep them in separate files.
## Configuration
### General
Entrypoints are part of the [static configuration](../getting-started/configuration-overview.md#the-static-configuration). You can define them using a toml file, CLI arguments, or a key-value store. See the [complete reference](../reference/entrypoints.md) for the list of available options.
??? example "Using the CLI"
Here is an example of using the CLI to define `entrypoints`:
```shell
--entryPoints='Name:http Address::80'
--entryPoints='Name:https Address::443 TLS'
```
!!! note
The whitespace character (` `) is the option separator, and the comma (`,`) is the value separator for lists.
The option names are case-insensitive.
!!! warning "Using Docker Compose Files"
The syntax for passing arguments inside a docker compose file is a little different. Here are two examples.
```yaml
traefik:
image: traefik
command:
- --defaultentrypoints=powpow
- "--entryPoints=Name:powpow Address::42 Compress:true"
```
or
```yaml
traefik:
image: traefik
command: --defaultentrypoints=powpow --entryPoints='Name:powpow Address::42 Compress:true'
```
## TLS
### Static Certificates
To add SNI support, define `certFile` and `keyFile`.
```toml
[entryPoints]
[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"
```
!!! note
If you provide an empty TLS configuration, default self-signed certificates will be generated.
### Dynamic Certificates
To add / remove TLS certificates while Traefik is running, the [file provider](../providers/file.md) supports Dynamic TLS certificates in its `[[tls]]` section.
### Mutual Authentication
Traefik supports both optional and non optional (defaut value) mutual authentication.
- When `optional = false`, Traefik accepts connections only from client presenting a certificate signed by a CA listed in `ClientCA.files`.
- When `optional = true`, Traefik authorizes connections from client presenting a certificate signed by an unknown CA.
??? example "Non Optional Mutual Authentication"
In the following example, both `snitest.com` and `snitest.org` will require client certificates.
```toml
[entryPoints]
[entryPoints.https]
address = ":443"
[entryPoints.https.tls]
[entryPoints.https.tls.ClientCA]
files = ["tests/clientca1.crt", "tests/clientca2.crt"]
optional = false
[[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"
```
!!! note "ClientCA.files"
You can use a file per `CA:s`, or a single file containing multiple `CA:s` (in `PEM` format).
`ClientCA.files` is not optional: every client will have to present a valid certificate. (This requirement will apply to every server certificate declared in the entrypoint.)
### Minimum TLS Version
??? example "Min TLS version & [cipherSuites](https://godoc.org/crypto/tls#pkg-constants)"
```toml
[entryPoints]
[entryPoints.https]
address = ":443"
[entryPoints.https.tls]
minVersion = "VersionTLS12"
cipherSuites = [
"TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
"TLS_RSA_WITH_AES_256_GCM_SHA384"
]
[[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"
```
### Strict SNI Checking
With strict SNI checking, Traefik won't allow connections without a matching certificate.
??? example "Strict SNI"
```toml
[entryPoints]
[entryPoints.https]
address = ":443"
[entryPoints.https.tls]
sniStrict = true
[[entryPoints.https.tls.certificates]]
certFile = "integration/fixtures/https/snitest.com.cert"
keyFile = "integration/fixtures/https/snitest.com.key"
```
### Default Certificate
Traefik can use a default certificate for connections without an SNI, or without a matching domain.
If no default certificate is provided, Traefik generates a self-signed and use it instead.
??? example "Setting a Default Certificate"
```toml
[entryPoints]
[entryPoints.https]
address = ":443"
[entryPoints.https.tls]
[entryPoints.https.tls.defaultCertificate]
certFile = "integration/fixtures/https/snitest.com.cert"
keyFile = "integration/fixtures/https/snitest.com.key"
```
!!! note "Only One Default Certificate"
There can only be one `defaultCertificate` per entrypoint.
## ProxyProtocol
Traefik supports [ProxyProtocol](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt).
??? example "Enabling Proxy Protocol with Trusted IPs"
```toml
[entryPoints]
[entryPoints.http]
address = ":80"
[entryPoints.http.proxyProtocol]
trustedIPs = ["127.0.0.1/32", "192.168.1.7"]
```
IPs in `trustedIPs` only will lead to remote client address replacement: Declare load-balancer IPs or CIDR range here.
??? example "Insecure Mode -- Testing Environnement Only"
In a test environments, you can configure Traefik to trust every incomming connection. Doing so, every remote client address will be replaced (`trustedIPs` won't have any effect)
```toml
[entryPoints]
[entryPoints.http]
address = ":80"
[entryPoints.http.proxyProtocol]
insecure = true
```
!!! warning "Queuing Traefik behind Another Load Balancer"
When queuing Traefik behind another load-balancer, make sure to configure Proxy Protocol on both sides.
Not doing so could introduce a security risk in your system (enabling request forgery).
## Forwarded Header
You can configure Traefik to trust the forwarded headers information (`X-Forwarded-*`)
??? example "Trusting Forwarded Headers from specific IPs"
```toml
[entryPoints]
[entryPoints.http]
address = ":80"
[entryPoints.http.forwardedHeaders]
trustedIPs = ["127.0.0.1/32", "192.168.1.7"]
```
??? example "Insecure Mode -- Always Trusting Forwarded Headers"
```toml
[entryPoints]
[entryPoints.http]
address = ":80"
[entryPoints.http.forwardedHeaders]
insecure = true
```

55
docs/content/routing/overview.md Normal file
View file

@ -0,0 +1,55 @@
# Overview
What's Happening to the Requests?
{: .subtitle }
Let's zoom on Traefik's architecture and talk about the components that enable the routes to be created.
First, when you start Traefik, you define [entrypoints](./entrypoints.md) (in their most basic forms, they are port numbers).
Then, connected to these entrypoints, [routers](./routers.md) analyze the incoming requests to see if they match a set of [rules](../routers#rule).
If they do, the router might transform the request using pieces of [middleware](../middlewares/overview.md) before forwarding them to your [services](./services.md).
![Architecture](../assets/img/architecture-overview.png)
## Clear Responsibilities
- [_Providers_](../providers/overview.md) discover the services that live on your infrastructure (their IP, health, ...)
- [_Entrypoints_](./entrypoints.md) listen for incomming traffic (ports, SSL, ...)
- [_Routers_](./routers.md) analyse the requests (host, path, headers, ...)
- [_Services_](./services.md) forward the request to your services (load balancing, ...)
- [_Middlewares_](../middlewares/overview.md) may update the request or make decisions based on the request (authentication, rate limiting, headers, ...)
## Example with a File Provider
Below is an example of a full configuration file for the [file provider](../providers/file.md) that forwards `http://domain/whoami/` requests to a service reachable on `http://private/whoami-service/`.
In the process, Traefik will make sure that the user is authenticated (using the [BasicAuth middleware](../middlewares/basicauth.md)).
```toml
[EntryPoints]
[EntryPoints.http]
address = ":8081" # Listen on port 8081 for incoming requests
[Providers]
# Enable the file provider to define routers / middlewares / services in a file
[Providers.file]
[Routers]
[Routers.to-whoami] # Define a connection between requests and services
rule = "Host(domain) && PathPrefix(/whoami/)"
middlewares = ["test-user"] # If the rule matches, applies the middleware
service = "whoami" # If the rule matches, forward to the whoami service (declared below)
[Middlewares]
[Middlewares.test-user.basicauth] # Define an authentication mechanism
users = ["test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"]
[Services]
[Services.whoami.loadbalancer] # Define how to reach an existing service on our infrastructure
[[Services.whoami.loadbalancer.servers]]
url = "http://private/whoami-service"
```
!!! note "The File Provider"
In this example, we use the [file provider](../providers/file.md).
Even if it is one of the least magical way of configuring Traefik, it explicitly describes every available notion.

134
docs/content/routing/routers.md Normal file
View file

@ -0,0 +1,134 @@
# Routers
Connecting Requests to Services
{: .subtitle }
![Routers](../assets/img/routers.png)
A router is in charge of connecting incoming requests to the services that can handle them.
In the process, routers may use pieces of [middleware](../middlewares/overview.md) to update the request, or act before forwarding the request to the service.
## Configuration Example
??? example "Requests /foo are Handled by service-foo -- Using the [File Provider](../providers/file.md)"
```toml
[Routers]
[Routers.my-router]
rule = "Path(/foo)"
service = "service-foo"
```
??? example "With a [Middleware](../middlewares/overview.md) -- using the [File Provider](../providers/file.md)"
```toml
[Routers]
[Routers.my-router]
rule = "Path(/foo)"
middlewares = ["authentication"] # declared elsewhere
service = "service-foo"
```
## Configuration
### EntryPoints
If not specified, routers will accept requests from all defined entrypoints.
If you want to limit the router scope to a set of entrypoint, set the entrypoints option.
??? example "Listens to Every EntryPoint"
```toml
[EntryPoints]
[EntryPoint.http]
# ...
[EntryPoint.https]
# ...
[EntryPoint.other]
# ...
[Routers]
[Routers.Router-1]
# By default, routers listen to every entrypoints
rule = "Host(traefik.io)"
service = "service-1"
```
??? example "Listens to Specific EntryPoints"
```toml
[EntryPoints]
[EntryPoint.http]
# ...
[EntryPoint.https]
# ...
[EntryPoint.other]
# ...
[Routers]
[Routers.Router-1]
entryPoints = ["https", "other"] # won't listen to entrypoint http
rule = "Host(traefik.io)"
service = "service-1"
```
### Rule
Rules are a set of matchers that determine if a particular request matches specific criteria.
If the rule is verified, then the router becomes active and calls middlewares, then forward the request to the service.
??? example "Host is traefik.io"
```
rule = "Host(`traefik.io`)"
```
??? example "Host is traefik.io OR Host is containo.us AND path is /traefik"
```
rule = "Host(`traefik.io`) || (Host(`containo.us`) && Path(`/traefik`))"
```
The table below lists all the available matchers:
| Rule | Description |
|--------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------|
| ``Headers(`key`, `value`)`` | Check if there is a key `key`defined in the headers, with the value `value` |
| ``HeadersRegexp(`key`, `regexp`)`` | Check if there is a key `key`defined in the headers, with a value that matches the regular expression `regexp` |
| ``Host(`domain-1`, ...)`` | Check if the request domain targets one of the given `domains`. |
| ``HostRegexp(`traefik.io`, `{subdomain:[a-z]+}.traefik.io`, ...)`` | Check if the request domain matches the given `regexp`. |
| `Method(methods, ...)` | Check if the request method is one of the given `methods` (`GET`, `POST`, `PUT`, `DELETE`, `PATCH`) |
| ``Path(`path`, `/articles/{category}/{id:[0-9]+}`, ...)`` | Match exact request path. It accepts a sequence of literal and regular expression paths. |
| ``PathPrefix(`/products/`, `/articles/{category}/{id:[0-9]+}`)`` | Match request prefix path. It accepts a sequence of literal and regular expression prefix paths. |
| ``Query(`foo=bar`, `bar=baz`)`` | Match` Query String parameters. It accepts a sequence of key=value pairs. |
!!! important "Regexp Syntax"
In order to use regular expressions with `Host` and `Path` expressions,
you must declare an arbitrarily named variable followed by the colon-separated regular expression, all enclosed in curly braces.
Any pattern supported by [Go's regexp package](https://golang.org/pkg/regexp/) may be used (example: `/posts/{id:[0-9]+}`).
!!! tip "Combining Matchers Using Operators and Parenthesis"
You can combine multiple matchers using the AND (`&&`) and OR (`||) operators. You can also use parenthesis.
!!! important "Rule, Middleware, and Services"
The rule is evaluated "before" any middleware has the opportunity to work, and "before" the request is forwarded to the service.
!!! tip "Path Vs PathPrefix"
Use `Path` if your service listens on the exact path only. For instance, `Path: /products` would match `/products` but not `/products/shoes`.
Use a `*Prefix*` matcher if your service listens on a particular base path but also serves requests on sub-paths.
For instance, `PathPrefix: /products` would match `/products` but also `/products/shoes` and `/products/shirts`.
Since the path is forwarded as-is, your service is expected to listen on `/products`.
### Middlewares
You can attach a list of [middlewares](../middlewares/overview.md) to the routers.
The middlewares will take effect only if the rule matches, and before forwarding the request to the service.
### Service
You must attach a [service](./services.md) per router.
Services are the target for the router.

190
docs/content/routing/services.md Normal file
View file

@ -0,0 +1,190 @@
# Services
Configuring How to Reach the Services
{: .subtitle }
![Services](../assets/img/services.png)
The `Services` are responsible for configuring how to reach the actual services that will eventually handle the incoming requests.
## Configuration Example
??? example "Declaring a Service with Two Servers (with Load Balancing) -- Using the [File Provider](../providers/file.md)"
```toml
[Services]
[Services.my-service.LoadBalancer]
method = "wrr" # Load Balancing based on weights
[[Services.my-service.LoadBalancer.servers]]
url = "http://private-ip-server-1/"
weight = 30 # 30% of the requests will go to that instance
[[Services.my-service.LoadBalancer.servers]]
url = "http://private-ip-server-2/"
weight = 70 # 70% of the requests will go to that instance
```
## Configuration
### General
Currently, the `LoadBalancer` service is the only supported kind of `Service` (see below).
However, since Traefik is an ever evolving project, other kind of Services will be available in the future,
reason why you have to specify what kind of service you declare.
### Load Balancer
The `LoadBalancer` service is able to load balance the requests between multiple instances of your programs.
??? example "Declaring a Service with Two Servers (with Load Balancing) -- Using the [File Provider](../providers/file.md)"
```toml
[Services]
[Services.my-service.LoadBalancer]
method = "wrr" # Load Balancing based on weights
[[Services.my-service.LoadBalancer.servers]]
url = "http://private-ip-server-1/"
weight = 50 # 50% of the requests will go to that instance
[[Services.my-service.LoadBalancer.servers]]
url = "http://private-ip-server-2/"
weight = 50 # 50% of the requests will go to that instance
```
#### Servers
Servers declare a single instance of your program.
The `url` option point to a specific instance.
The `weight` option defines the weight of the server for the load balancing algorithm.
!!! note
Paths in the servers' `url` have no effet.
If you want the requests to be sent to a specific path on your servers,
configure your [`routers`](./routers.md) to use a corresponding [Middleware](../middlewares/overview.md) (e.g. the [AddPrefix](../middlewares/addprefix.md) or [ReplacePath](../middlewares/replacepath.md)) middlewares.
??? example "A Service with One Server -- Using the [File Provider](../providers/file.md)"
```toml
[Services]
[Services.my-service.LoadBalancer]
[[Services.my-service.LoadBalancer.servers]]
url = "http://private-ip-server-1/"
```
#### Load-balancing
Various methods of load balancing are supported:
- `wrr`: Weighted Round Robin.
- `drr`: Dynamic Round Robin: increases weights on servers that perform better than others (rolls back to original weights when the server list is updated)
??? example "Load Balancing Using DRR -- Using the [File Provider](../providers/file.md)"
```toml
[Services]
[Services.my-service.LoadBalancer]
method = "drr"
[[Services.my-service.LoadBalancer.servers]]
url = "http://private-ip-server-1/"
[[Services.my-service.LoadBalancer.servers]]
url = "http://private-ip-server-1/"
```
#### Sticky sessions
When sticky sessions are enabled, a cookie is set on the initial request to track which server handles the first response.
On subsequent requests, the client is forwarded to the same server.
!!! note "Stickiness & Unhealthy Servers"
If the server specified in the cookie becomes unhealthy, the request will be forwarded to a new server (and the cookie will keep track of the new server).
!!! note "Cookie Name"
The default cookie name is an abbreviation of a sha1 (ex: `_1d52e`).
??? example "Adding Stickiness"
```toml
[Services]
[Services.my-service]
[Services.my-service.LoadBalancer.stickiness]
```
??? example "Adding Stickiness with a Custom Cookie Name"
```toml
[Services]
[Services.my-service]
[Services.my-service.LoadBalancer.stickiness]
cookieName = "my_stickiness_cookie_name"
```
#### Health Check
Configure healthcheck to remove unhealthy servers from the load balancing rotation.
Traefik will consider your servers healthy as long as they return status codes between `2XX` and `3XX` to the health check requests (carried out every `interval`).
Below are the available options for the health check mechanism:
- `path` is appended to the server URL to set the healcheck endpoint.
- `scheme`, if defined, will replace the server URL `scheme` for the healthcheck endpoint
- `hostname`, if defined, will replace the server URL `hostname` for the healthcheck endpoint.
- `port`, if defined, will replace the server URL `port` for the healthcheck endpoint.
- `interval` defines the frequency of the healthcheck calls.
- `timeout` defines the maximum duration Traefik will wait for a healthcheck request before considering the server failed (unhealthy).
- `headers` defines custom headers to be sent to the healthcheck endpoint.
!!! note "Interval & Timeout Format"
Interval and timeout are to be given in a format understood by [time.ParseDuration](https://golang.org/pkg/time/#ParseDuration).
The interval must be greater than the timeout. If configuration doesn't reflect this, the interval will be set to timeout + 1 second.
!!! note "Recovering Servers"
Traefik keeps monitoring the health of unhealthy servers.
If a server has recovered (returning `2xx` -> `3xx` responses again), it will be added back to the load balacer rotation pool.
??? example "Custom Interval & Timeout -- Using the File Provider"
```toml
[Services]
[Servicess.Service-1]
[Services.Service-1.healthcheck]
path = "/health"
interval = "10s"
timeout = "3s"
```
??? example "Custom Port -- Using the File Provider"
```toml
[Services]
[Services.Service-1]
[Services.Service-1.healthcheck]
path = "/health"
port = 8080
```
??? example "Custom Scheme -- Using the File Provider"
```toml
[Services]
[Services.Service-1]
[Services.Service-1.healthcheck]
path = "/health"
scheme = "http"
```
??? example "Additional HTTP Headers -- Using the File Provider"
```toml
[Services]
[Services.Service-1]
[Servicess.Service-1.healthcheck]
path = "/health"
[Service.Service-1.healthcheck.headers]
My-Custom-Header = "foo"
My-Header = "bar"
```