From 3ebed4ff40c1e696caf085aa6f84dd7ac689d0f4 Mon Sep 17 00:00:00 2001 From: Damien Duportal Date: Mon, 7 Oct 2019 14:38:06 +0200 Subject: [PATCH] Clarifies how to configure and access the dashboard in the api & dashboard documentations --- docs/content/migration/v1-to-v2.md | 2 +- docs/content/operations/dashboard.md | 71 +++++++++++++++++++++------- 2 files changed, 54 insertions(+), 19 deletions(-) diff --git a/docs/content/migration/v1-to-v2.md b/docs/content/migration/v1-to-v2.md index e302358e1..fa2489589 100644 --- a/docs/content/migration/v1-to-v2.md +++ b/docs/content/migration/v1-to-v2.md @@ -824,7 +824,7 @@ Each root item has been moved to a related section or removed. ## Dashboard -You need to activate the [API](../operations/dashboard.md#enabling-the-dashboard) to access the dashboard. +You need to activate the API to access the [dashboard](../operations/dashboard.md). As the dashboard access is now secured by default you can either: * define a [specific router](../operations/api.md#configuration) with the `api@internal` service and one authentication middleware like the following example diff --git a/docs/content/operations/dashboard.md b/docs/content/operations/dashboard.md index 74dfe5ec6..9dc77bb5e 100644 --- a/docs/content/operations/dashboard.md +++ b/docs/content/operations/dashboard.md @@ -3,24 +3,32 @@ See What's Going On {: .subtitle } -The dashboard is the central place that shows you the current active routes handled by Traefik. +The dashboard is the central place that shows you the current active routes handled by Traefik.
Dashboard - Providers
The dashboard in action
-By default, the dashboard is available on `/dashboard` on port `:8080`. -There is also a redirect of `/` to `/dashboard`, but one should not rely on that property as it is bound to change, -and it might make for confusing routing rules anyway. +The dashboard is available at the same location as the [API](./api.md) but on the path `/dashboard/` by default. -!!! info "Did You Know?" - It is possible to customize the dashboard endpoint. - To learn how, refer to the [API documentation](./api.md) - -## Enabling the Dashboard +!!! warning "The trailing slash `/` in `/dashboard/` is mandatory" -To enable the dashboard, you need to enable [Traefik's API](./api.md). +There are 2 ways to configure and access the dashboard: + +- [Secure mode (Recommended)](#secure-mode) +- [Insecure mode](#insecure-mode) + +!!! note "" + There is also a redirect of the path `/` to the path `/dashboard/`, + but one should not rely on that property as it is bound to change, + and it might make for confusing routing rules anyway. + +## Secure Mode + +This is the **recommended** method. + +Start by enabling the dashboard by using the following option from [Traefik's API](./api.md): ```toml tab="File (TOML)" [api] @@ -51,12 +59,39 @@ api: --api.dashboard=true ``` -!!! important "API/Dashboard Security" - - To secure your dashboard, the use of a `service` named `api@internal` is mandatory and requires the definition of a router using one or more security [middlewares](../middlewares/overview.md) - like authentication ([basicAuth](../middlewares/basicauth.md) , [digestAuth](../middlewares/digestauth.md), [forwardAuth](../middlewares/forwardauth.md)) or [whitelisting](../middlewares/ipwhitelist.md). - More information about `api@internal` can be found in the [API documentation](./api.md#configuration) +Then specify a router associated to the service `api@internal` to allow: -!!! info "Did You Know?" - The API provides more features than the Dashboard. - To learn more about it, refer to the [API documentation](./api.md) +- Defining one or more security features through [middlewares](../middlewares/overview.md) + like authentication ([basicAuth](../middlewares/basicauth.md) , [digestAuth](../middlewares/digestauth.md), + [forwardAuth](../middlewares/forwardauth.md)) or [whitelisting](../middlewares/ipwhitelist.md). + +- Defining your own [HTTP routing rule](../../routing/routers/#rule) for accessing the dashboard, + through Traefik itself (sometimes referred as "Traefik-ception"). + +Please visit the ["Configuration" section of the API documentation](./api.md#configuration) +to learn about configuring a router with the service `api@internal` and enabling the security features. + +## Insecure Mode + +This mode is not recommended because it does not allow the use of security features. + +To enable the "insecure mode", use the following options from [Traefik's API](./api.md#insecure): + +```toml tab="File (TOML)" +[api] + dashboard = true + insecure = true +``` + +```yaml tab="File (YAML)" +api: + dashboard: true + insecure: true +``` + +```bash tab="CLI" +--api.dashboard=true --api.insecure=true +``` + +You can now access the dashboard on the port `8080` of the Traefik instance, +at the following URL: `http://:8080/dashboard/` (trailing slash is mandatory).