From d54777236ccd54b247defcdd48d9e0735d6fde8a Mon Sep 17 00:00:00 2001 From: SALLEYRON Julien Date: Fri, 16 Feb 2018 10:32:03 +0100 Subject: [PATCH] Update documentation on onHostRule, ping examples, and web deprecation --- docs/configuration/acme.md | 21 +++--- docs/configuration/api.md | 9 ++- docs/configuration/backends/web.md | 107 +++++++++++++++++++++++------ docs/configuration/entrypoints.md | 10 +-- docs/configuration/ping.md | 4 +- docs/user-guide/examples.md | 79 ++++++++------------- 6 files changed, 144 insertions(+), 86 deletions(-) diff --git a/docs/configuration/acme.md b/docs/configuration/acme.md index 3248ecc6b..83bcc9eac 100644 --- a/docs/configuration/acme.md +++ b/docs/configuration/acme.md @@ -113,7 +113,7 @@ entryPoint = "https" # Required # entryPoint = "http" - + # Use a DNS-01 acme challenge rather than TLS-SNI-01 challenge # # Optional @@ -135,6 +135,7 @@ entryPoint = "https" # # delayBeforeCheck = 0 ``` + !!! note Even if `TLS-SNI-01` challenge is [disabled](https://community.letsencrypt.org/t/2018-01-11-update-regarding-acme-tls-sni-and-shared-hosting-infrastructure/50188) for the moment, it stays the _by default_ ACME Challenge in Træfik. If `TLS-SNI-01` challenge is not re-enabled in the future, it we will be removed from Træfik. @@ -149,12 +150,13 @@ entryPoint = "https" Let's Encrypt functionality will be limited until Træfik is restarted. If Let's Encrypt is not reachable, these certificates will be used : + - ACME certificates already generated before downtime - Expired ACME certificates - Provided certificates !!! note - Default Træfik certificate will be used instead of ACME certificates for new (sub)domains (which need Let's Encrypt challenge). + Default Træfik certificate will be used instead of ACME certificates for new (sub)domains (which need Let's Encrypt challenge). ### `storage` @@ -168,6 +170,7 @@ storage = "acme.json" The `storage` option sets where are stored your ACME certificates. There are two kind of `storage` : + - a JSON file, - a KV store entry. @@ -182,7 +185,7 @@ There are two kind of `storage` : #### Store data in a file -ACME certificates can be stored in a JSON file which with the `600` right mode. +ACME certificates can be stored in a JSON file which with the `600` right mode. There are two ways to store ACME certificates in a file from Docker: @@ -240,6 +243,8 @@ entryPoint = "https" Specify the entryPoint to use during the challenges. ```toml +defaultEntryPoints = ["http", "http"] + [entryPoints] [entryPoints.http] address = ":80" @@ -272,7 +277,7 @@ Use `DNS-01` challenge to generate/renew ACME certificates. # ... ``` -#### `provider` +#### `provider` Select the provider that matches the DNS domain that will host the challenge TXT record, and provide environment variables to enable setting it: @@ -326,11 +331,11 @@ onDemand = true 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. +This will request a certificate from Let's Encrypt during the first TLS handshake for a host name that does not yet have a certificate. !!! warning - TLS handshakes will be slow when requesting a hostname certificate for the first time, this can lead to DoS attacks. - + TLS handshakes will be slow when requesting a host name certificate for the first time, this can lead to DoS attacks. + !!! warning Take note that Let's Encrypt have [rate limiting](https://letsencrypt.org/docs/rate-limits). @@ -343,7 +348,7 @@ onHostRule = true # ... ``` -Enable certificate generation on frontends Host rules. +Enable certificate generation on frontends `Host` rules (for frontends wired on the `acme.entryPoint`). This will request a certificate from Let's Encrypt for each frontend with a Host rule. diff --git a/docs/configuration/api.md b/docs/configuration/api.md index ac6afd7dc..298812f3b 100644 --- a/docs/configuration/api.md +++ b/docs/configuration/api.md @@ -1,5 +1,7 @@ # API Definition +## Configuration + ```toml # API definition [api] @@ -28,6 +30,8 @@ debug = true ``` +For more customization, see [entry points](/configuration/entrypoints/) documentation and [examples](/user-guide/examples/#ping-health-check). + ## Web UI ![Web UI Providers](/img/web.frontend.png) @@ -42,7 +46,7 @@ | `/health` | `GET` | json health metrics | | `/api` | `GET` | Configuration for all providers | | `/api/providers` | `GET` | Providers | -| `/api/providers/{provider}` | `GET`, `PUT` | Get or update provider | +| `/api/providers/{provider}` | `GET`, `PUT` | Get or update provider (1) | | `/api/providers/{provider}/backends` | `GET` | List backends | | `/api/providers/{provider}/backends/{backend}` | `GET` | Get backend | | `/api/providers/{provider}/backends/{backend}/servers` | `GET` | List servers in backend | @@ -52,6 +56,8 @@ | `/api/providers/{provider}/frontends/{frontend}/routes` | `GET` | List routes in a frontend | | `/api/providers/{provider}/frontends/{frontend}/routes/{route}` | `GET` | Get a route in a frontend | +<1> See [Rest](/configuration/backends/rest/#api) for more information. + !!! warning For compatibility reason, when you activate the rest provider, you can use `web` or `rest` as `provider` value. But be careful, in the configuration for all providers the key is still `web`. @@ -185,6 +191,7 @@ curl -s "http://localhost:8080/health" | jq . ## Metrics You can enable Traefik to export internal metrics to different monitoring systems. + ```toml [api] # ... diff --git a/docs/configuration/backends/web.md b/docs/configuration/backends/web.md index a5e185560..6e3b2852c 100644 --- a/docs/configuration/backends/web.md +++ b/docs/configuration/backends/web.md @@ -36,7 +36,6 @@ address = ":8080" # readOnly = true - # Set the root path for webui and API # # Deprecated @@ -55,13 +54,13 @@ readOnly = true ### Authentication !!! note - The `/ping` path of the api is excluded from authentication (since 1.4). + The `/ping` path of the API is excluded from authentication (since 1.4). #### Basic Authentication Passwords can be encoded in MD5, SHA1 and BCrypt: you can use `htpasswd` to generate those ones. -Users can be specified directly in the toml file, or indirectly by referencing an external file; +Users can be specified directly in the TOML file, or indirectly by referencing an external file; if both are provided, the two are merged, with external file contents having precedence. ```toml @@ -80,7 +79,7 @@ usersFile = "/path/to/.htpasswd" You can use `htdigest` to generate those ones. -Users can be specified directly in the toml file, or indirectly by referencing an external file; +Users can be specified directly in the TOML file, or indirectly by referencing an external file; if both are provided, the two are merged, with external file contents having precedence ```toml @@ -98,7 +97,7 @@ usersFile = "/path/to/.htdigest" ## Metrics -You can enable Traefik to export internal metrics to different monitoring systems. +You can enable Træfik to export internal metrics to different monitoring systems. ### Prometheus @@ -114,7 +113,7 @@ You can enable Traefik to export internal metrics to different monitoring system # Optional # Default: [0.1, 0.3, 1.2, 5] buckets=[0.1,0.3,1.2,5.0] - + # ... ``` @@ -221,7 +220,7 @@ recentErrors = 10 |-----------------------------------------------------------------|:-------------:|----------------------------------------------------------------------------------------------------| | `/` | `GET` | Provides a simple HTML frontend of Træfik | | `/ping` | `GET`, `HEAD` | A simple endpoint to check for Træfik process liveness. Return a code `200` with the content: `OK` | -| `/health` | `GET` | json health metrics | +| `/health` | `GET` | JSON health metrics | | `/api` | `GET` | Configuration for all providers | | `/api/providers` | `GET` | Providers | | `/api/providers/{provider}` | `GET`, `PUT` | Get or update provider | @@ -244,7 +243,7 @@ curl -sv "http://localhost:8080/ping" ``` ```shell * Trying ::1... -* Connected to localhost (::1) port 8080 (#0) +* Connected to localhost (::1) port 8080 (\#0) > GET /ping HTTP/1.1 > Host: localhost:8080 > User-Agent: curl/7.43.0 @@ -255,7 +254,7 @@ curl -sv "http://localhost:8080/ping" < Content-Length: 2 < Content-Type: text/plain; charset=utf-8 < -* Connection #0 to host localhost left intact +* Connection \#0 to host localhost left intact OK ``` @@ -309,7 +308,7 @@ curl -s "http://localhost:8080/health" | jq . "status": "Internal Server Error", // request HTTP method "method": "GET", - // request hostname + // request host name "host": "localhost", // request path "path": "/path", @@ -385,23 +384,28 @@ curl -s "http://localhost:8080/api" | jq . } ``` -## Path +### Deprecation compatibility -As web is deprecated, you can handle the `Path` option like this +#### Path + +As the web provider is deprecated, you can handle the `Path` option like this: ```toml -[entrypoints.http] -address=":80" +defaultEntryPoints = ["http"] -[entrypoints.dashboard] -address=":8080" +[entryPoints] + [entryPoints.http] + address = ":80" -[entrypoints.api] -address=":8081" + [entryPoints.dashboard] + address = ":8080" -#Activate API and Dashboard + [entryPoints.api] + address = ":8081" + +# Activate API and Dashboard [api] -entrypoint="api" +entryPoint = "api" [file] [backends] @@ -411,8 +415,67 @@ entrypoint="api" [frontends] [frontends.frontend1] - entrypoints=["dashboard"] + entryPoints = ["dashboard"] backend = "backend1" [frontends.frontend1.routes.test_1] rule = "PathPrefixStrip:/yourprefix;PathPrefix:/yourprefix" -``` \ No newline at end of file +``` + +#### Address + +As the web provider is deprecated, you can handle the `Address` option like this: + +```toml +defaultEntryPoints = ["http"] + +[entryPoints] + [entryPoints.http] + address = ":80" + + [entryPoints.ping] + address = ":8082" + + [entryPoints.api] + address = ":8083" + +[ping] +entryPoint = "ping" + +[api] +entryPoint = "api" +``` + +In the above example, you would access a regular path, administration panel, and health-check as follows: + +* Regular path: `http://hostname:80/foo` +* Admin Panel: `http://hostname:8083/` +* Ping URL: `http://hostname:8082/ping` + +In the above example, it is _very_ important to create a named dedicated entry point, and do **not** include it in `defaultEntryPoints`. +Otherwise, you are likely to expose _all_ services via that entry point. + +#### Authentication + +As the web provider is deprecated, you can handle the `auth` option like this: + +```toml +defaultEntryPoints = ["http"] + +[entryPoints] + [entryPoints.http] + address = ":80" + + [entryPoints.api] + address=":8080" + [entryPoints.api.auth] + [entryPoints.api.auth.basic] + users = [ + "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/", + "test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0", + ] + +[api] +entrypoint="api" +``` + +For more information, see [entry points](/configuration/entrypoints/) . diff --git a/docs/configuration/entrypoints.md b/docs/configuration/entrypoints.md index a8f7eefcc..9ec90931b 100644 --- a/docs/configuration/entrypoints.md +++ b/docs/configuration/entrypoints.md @@ -234,9 +234,9 @@ In the example below both `snitest.com` and `snitest.org` will require client ce ### Basic Authentication -Passwords can be encoded in MD5, SHA1 and BCrypt: you can use `htpasswd` to generate those ones. +Passwords can be encoded in MD5, SHA1 and BCrypt: you can use `htpasswd` to generate them. -Users can be specified directly in the toml file, or indirectly by referencing an external file; +Users can be specified directly in the TOML file, or indirectly by referencing an external file; if both are provided, the two are merged, with external file contents having precedence. ```toml @@ -251,9 +251,9 @@ Users can be specified directly in the toml file, or indirectly by referencing a ### Digest Authentication -You can use `htdigest` to generate those ones. +You can use `htdigest` to generate them. -Users can be specified directly in the toml file, or indirectly by referencing an external file; +Users can be specified directly in the TOML file, or indirectly by referencing an external file; if both are provided, the two are merged, with external file contents having precedence ```toml @@ -271,7 +271,7 @@ Users can be specified directly in the toml file, or indirectly by referencing a This configuration will first forward the request to `http://authserver.com/auth`. If the response code is 2XX, access is granted and the original request is performed. -Otherwise, the response from the auth server is returned. +Otherwise, the response from the authentication server is returned. ```toml [entryPoints] diff --git a/docs/configuration/ping.md b/docs/configuration/ping.md index bfe27b79a..de1d805e5 100644 --- a/docs/configuration/ping.md +++ b/docs/configuration/ping.md @@ -1,5 +1,7 @@ # Ping Definition +## Configuration + ```toml # Ping definition [ping] @@ -19,7 +21,7 @@ !!! warning Even if you have authentication configured on entry point, the `/ping` path of the api is excluded from authentication. -### Example +## Example ```shell curl -sv "http://localhost:8080/ping" diff --git a/docs/user-guide/examples.md b/docs/user-guide/examples.md index ff2813a6c..c7f6f4c86 100644 --- a/docs/user-guide/examples.md +++ b/docs/user-guide/examples.md @@ -91,7 +91,7 @@ entryPoint = "https" This configuration allows generating Let's Encrypt certificates (thanks to `HTTP-01` challenge) for the four domains `local[1-4].com` with described SANs. -Traefik generates these certificates when it starts and it needs to be restart if new domains are added. +Træfik generates these certificates when it starts and it needs to be restart if new domains are added. ### OnHostRule option (with HTTP challenge) @@ -126,9 +126,9 @@ entryPoint = "https" This configuration allows generating Let's Encrypt certificates (thanks to `HTTP-01` challenge) for the four domains `local[1-4].com`. -Traefik generates these certificates when it starts. +Træfik generates these certificates when it starts. -If a backend is added with a `onHost` rule, Traefik will automatically generate the Let's Encrypt certificate for the new domain. +If a backend is added with a `onHost` rule, Træfik will automatically generate the Let's Encrypt certificate for the new domain (for frontends wired on the `acme.entryPoint`). ### OnDemand option (with HTTP challenge) @@ -152,11 +152,10 @@ entryPoint = "https" This configuration allows generating a Let's Encrypt certificate (thanks to `HTTP-01` challenge) during the first HTTPS request on a new domain. - !!! note This option simplifies the configuration but : - * TLS handshakes will be slow when requesting a hostname certificate for the first time, this can leads to DDoS attacks. + * TLS handshakes will be slow when requesting a host name certificate for the first time, this can leads to DDoS attacks. * Let's Encrypt have rate limiting: https://letsencrypt.org/docs/rate-limits That's why, it's better to use the `onHostRule` option if possible. @@ -191,7 +190,7 @@ entryPoint = "https" ``` DNS challenge needs environment variables to be executed. -This variables have to be set on the machine/container which host Traefik. +These variables have to be set on the machine/container which host Træfik. These variables are described [in this section](/configuration/acme/#provider). @@ -218,7 +217,7 @@ entryPoint = "https" entryPoint = "http" ``` -Traefik will only try to generate a Let's encrypt certificate (thanks to `HTTP-01` challenge) if the domain cannot be checked by the provided certificates. +Træfik will only try to generate a Let's encrypt certificate (thanks to `HTTP-01` challenge) if the domain cannot be checked by the provided certificates. ### Cluster mode @@ -292,14 +291,14 @@ The `consul` provider contains the configuration. rule = "Path:/test" ``` -## Enable Basic authentication in an entrypoint +## Enable Basic authentication in an entry point With two user/pass: - `test`:`test` - `test2`:`test2` -Passwords are encoded in MD5: you can use htpasswd to generate those ones. +Passwords are encoded in MD5: you can use `htpasswd` to generate them. ```toml defaultEntryPoints = ["http"] @@ -337,7 +336,7 @@ providersThrottleDuration = "5s" idleTimeout = "360s" ``` -## Securing Ping Health Check +## Ping Health Check The `/ping` health-check URL is enabled with the command-line `--ping` or config file option `[ping]`. Thus, if you have a regular path for `/foo` and an entrypoint on `:80`, you would access them as follows: @@ -346,40 +345,36 @@ Thus, if you have a regular path for `/foo` and an entrypoint on `:80`, you woul * Admin panel: `http://hostname:8080/` * Ping URL: `http://hostname:8080/ping` -However, for security reasons, you may want to be able to expose the `/ping` health-check URL to outside health-checkers, e.g. an Internet service or cloud load-balancer, _without_ exposing your admin panel's port. +However, for security reasons, you may want to be able to expose the `/ping` health-check URL to outside health-checkers, e.g. an Internet service or cloud load-balancer, _without_ exposing your administration panel's port. In many environments, the security staff may not _allow_ you to expose it. You have two options: -* Enable `/ping` on a regular entrypoint +* Enable `/ping` on a regular entry point * Enable `/ping` on a dedicated port -### Enable ping health check on a regular entrypoint +### Enable ping health check on a regular entry point -To proxy `/ping` from a regular entrypoint to the admin one without exposing the panel, do the following: +To proxy `/ping` from a regular entry point to the administration one without exposing the panel, do the following: ```toml -[backends] - [backends.traefik] - [backends.traefik.servers.server1] - url = "http://localhost:8080" - weight = 10 +defaultEntryPoints = ["http"] + +[entryPoints] + [entryPoints.http] + address = ":80" + +[ping] +entryPoint = "http" -[frontends] - [frontends.traefikadmin] - backend = "traefik" - [frontends.traefikadmin.routes.ping] - rule = "Path:/ping" ``` -The above creates a new backend called `traefik`, listening on `http://localhost:8080`, i.e. the local admin port. -We only expose the admin panel via the `frontend` named `traefikadmin`, and only expose the `/ping` Path. -Be careful with the `traefikadmin` frontend. If you do _not_ specify a `Path:` rule, you would expose the entire dashboard. +The above link `ping` on the `http` entry point and then expose it on port `80` ### Enable ping health check on dedicated port -If you do not want to or cannot expose the health-check on a regular entrypoint - e.g. your security rules do not allow it, or you have a conflicting path - then you can enable health-check on its own entrypoint. -Use the following config: +If you do not want to or cannot expose the health-check on a regular entry point - e.g. your security rules do not allow it, or you have a conflicting path - then you can enable health-check on its own entry point. +Use the following configuration: ```toml defaultEntryPoints = ["http"] @@ -390,32 +385,18 @@ defaultEntryPoints = ["http"] [entryPoints.ping] address = ":8082" -[backends] - [backends.traefik] - [backends.traefik.servers.server1] - url = "http://localhost:8080" - weight = 10 - -[frontends] - [frontends.traefikadmin] - backend = "traefik" - entrypoints = ["ping"] - [frontends.traefikadmin.routes.ping] - rule = "Path:/ping" +[ping] +entryPoint = "ping" ``` -The above is similar to the previous example, but instead of enabling `/ping` on the _default_ entrypoint, we enable it on a _dedicated_ entrypoint. +The above is similar to the previous example, but instead of enabling `/ping` on the _default_ entry point, we enable it on a _dedicated_ entry point. -In the above example, you would access a regular path, admin panel and health-check as follows: +In the above example, you would access a regular path and health-check as follows: * Regular path: `http://hostname:80/foo` -* Admin panel: `http://hostname:8080/` * Ping URL: `http://hostname:8082/ping` Note the dedicated port `:8082` for `/ping`. -In the above example, it is _very_ important to create a named dedicated entrypoint, and do **not** include it in `defaultEntryPoints`. -Otherwise, you are likely to expose _all_ services via that entrypoint. - -In the above example, we have two entrypoints, `http` and `ping`, but we only included `http` in `defaultEntryPoints`, while explicitly tying `frontend.traefikadmin` to the `ping` entrypoint. -This ensures that all the "normal" frontends will be exposed via entrypoint `http` and _not_ via entrypoint `ping`. +In the above example, it is _very_ important to create a named dedicated entry point, and do **not** include it in `defaultEntryPoints`. +Otherwise, you are likely to expose _all_ services via this entry point.