Enhance API, REST, ping documentation.

docs/configuration/api.md

@@ -43,7 +43,7 @@ For more customization, see [entry points](/configuration/entrypoints/) document
 | Path                                                            | Method           | Description                               |
 |-----------------------------------------------------------------|------------------|-------------------------------------------|
 | `/`                                                             |     `GET`        | Provides a simple HTML frontend of Træfik |
-| `/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 (1)                |
@@ -62,7 +62,102 @@ For more customization, see [entry points](/configuration/entrypoints/) document
     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`.
 
-### Provider configurations
+### Address / Port
+
+You can define a custom address/port like this:
+
+```toml
+defaultEntryPoints = ["http"]
+
+[entryPoints]
+  [entryPoints.http]
+  address = ":80"
+
+  [entryPoints.foo]
+  address = ":8082"
+
+  [entryPoints.bar]
+  address = ":8083"
+
+[ping]
+entryPoint = "foo"
+
+[api]
+entryPoint = "bar"
+```
+
+In the above example, you would access a regular path, administration panel, and health-check as follows:
+
+* Regular path: `http://hostname:80/path`
+* 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.
+
+### Custom Path
+
+You can define a custom path like this:
+
+```toml
+defaultEntryPoints = ["http"]
+
+[entryPoints]
+  [entryPoints.http]
+  address = ":80"
+
+  [entryPoints.foo]
+  address = ":8080"
+
+  [entryPoints.bar]
+  address = ":8081"
+
+# Activate API and Dashboard
+[api]
+entryPoint = "bar"
+dashboard = true
+
+[file]
+  [backends]
+    [backends.backend1]
+      [backends.backend1.servers.server1]
+      url = "http://127.0.0.1:8081"
+
+  [frontends]
+    [frontends.frontend1]
+    entryPoints = ["foo"]
+    backend = "backend1"
+      [frontends.frontend1.routes.test_1]
+      rule = "PathPrefixStrip:/yourprefix;PathPrefix:/yourprefix"
+```
+
+### Authentication
+
+You can define the authentication like this:
+
+```toml
+defaultEntryPoints = ["http"]
+
+[entryPoints]
+  [entryPoints.http]
+  address = ":80"
+
+ [entryPoints.foo]
+   address=":8080"
+   [entryPoints.foo.auth]
+     [entryPoints.foo.auth.basic]
+       users = [
+         "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/",
+         "test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0",
+       ]
+
+[api]
+entrypoint="foo"
+```
+
+For more information, see [entry points](/configuration/entrypoints/) .
+
+### Provider call example
 
 ```shell
 curl -s "http://localhost:8080/api" | jq .

docs/configuration/backends/rest.md

@@ -29,9 +29,10 @@ Træfik can be configured:
 
 
 ```shell
-curl -XPUT @file "http://localhost:8080/api" 
+curl -XPUT @file "http://localhost:8080/api/providers/rest"
 ```
-with `@file`
+
+with `@file`:
 ```json
 {
     "frontends": {

docs/configuration/backends/web.md

@@ -386,41 +386,6 @@ curl -s "http://localhost:8080/api" | jq .
 
 ### Deprecation compatibility
 
-#### Path
-
-As the web provider is deprecated, you can handle the `Path` option like this:
-
-```toml
-defaultEntryPoints = ["http"]
-
-[entryPoints]
-  [entryPoints.http]
-  address = ":80"
-
-  [entryPoints.dashboard]
-  address = ":8080"
-
-  [entryPoints.api]
-  address = ":8081"
-
-# Activate API and Dashboard
-[api]
-entryPoint = "api"
-
-[file]
-  [backends]
-    [backends.backend1]
-      [backends.backend1.servers.server1]
-      url = "http://127.0.0.1:8081"
-
-  [frontends]
-    [frontends.frontend1]
-    entryPoints = ["dashboard"]
-    backend = "backend1"
-      [frontends.frontend1.routes.test_1]
-      rule = "PathPrefixStrip:/yourprefix;PathPrefix:/yourprefix"
-```
-
 #### Address
 
 As the web provider is deprecated, you can handle the `Address` option like this:
@@ -432,28 +397,64 @@ defaultEntryPoints = ["http"]
   [entryPoints.http]
   address = ":80"
 
-  [entryPoints.ping]
+  [entryPoints.foo]
   address = ":8082"
 
-  [entryPoints.api]
+  [entryPoints.bar]
   address = ":8083"
 
 [ping]
-entryPoint = "ping"
+entryPoint = "foo"
 
 [api]
-entryPoint = "api"
+entryPoint = "bar"
 ```
 
 In the above example, you would access a regular path, administration panel, and health-check as follows:
 
-* Regular path: `http://hostname:80/foo`
+* Regular path: `http://hostname:80/path`
 * 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.
 
+#### Path
+
+As the web provider is deprecated, you can handle the `Path` option like this:
+
+```toml
+defaultEntryPoints = ["http"]
+
+[entryPoints]
+  [entryPoints.http]
+  address = ":80"
+
+  [entryPoints.foo]
+  address = ":8080"
+
+  [entryPoints.bar]
+  address = ":8081"
+
+# Activate API and Dashboard
+[api]
+entryPoint = "bar"
+dashboard = true
+
+[file]
+  [backends]
+    [backends.backend1]
+      [backends.backend1.servers.server1]
+      url = "http://127.0.0.1:8081"
+
+  [frontends]
+    [frontends.frontend1]
+    entryPoints = ["foo"]
+    backend = "backend1"
+      [frontends.frontend1.routes.test_1]
+      rule = "PathPrefixStrip:/yourprefix;PathPrefix:/yourprefix"
+```
+
 #### Authentication
 
 As the web provider is deprecated, you can handle the `auth` option like this:
@@ -465,17 +466,17 @@ defaultEntryPoints = ["http"]
   [entryPoints.http]
   address = ":80"
 
- [entryPoints.api]
+ [entryPoints.foo]
    address=":8080"
-   [entryPoints.api.auth]
+   [entryPoints.foo.auth]
-     [entryPoints.api.auth.basic]
+     [entryPoints.foo.auth.basic]
        users = [
          "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/",
          "test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0",
        ]
 
 [api]
-entrypoint="api"
+entrypoint="foo"
 ```
 
 For more information, see [entry points](/configuration/entrypoints/) .

docs/configuration/ping.md

@@ -21,24 +21,67 @@
 !!! warning
     Even if you have authentication configured on entry point, the `/ping` path of the api is excluded from authentication.
 
-## Example
+## Examples
+
+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:
+
+* Regular path: `http://hostname:80/foo`
+* 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 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 entry point
+* Enable `/ping` on a dedicated port
+
+### Ping health check on a regular entry point
+
+To proxy `/ping` from a regular entry point to the administration one without exposing the panel, do the following:
+
+```toml
+defaultEntryPoints = ["http"]
+
+[entryPoints]
+  [entryPoints.http]
+  address = ":80"
+
+[ping]
+entryPoint = "http"
 
-```shell
-curl -sv "http://localhost:8080/ping"
 ```
-```shell
+
-*   Trying ::1...
+The above link `ping` on the `http` entry point and then expose it on port `80`
-* Connected to localhost (::1) port 8080 (#0)
+
-> GET /ping HTTP/1.1
+### Enable ping health check on dedicated port
-> Host: localhost:8080
+
-> User-Agent: curl/7.43.0
+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.
-> Accept: */*
+Use the following configuration:
->
+
-< HTTP/1.1 200 OK
+```toml
-< Date: Thu, 25 Aug 2016 01:35:36 GMT
+defaultEntryPoints = ["http"]
-< Content-Length: 2
+
-< Content-Type: text/plain; charset=utf-8
+[entryPoints]
-<
+  [entryPoints.http]
-* Connection #0 to host localhost left intact
+  address = ":80"
-OK
+  [entryPoints.ping]
+  address = ":8082"
+
+[ping]
+entryPoint = "ping"
 ```
+
+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 and health-check as follows:
+
+* Regular path: `http://hostname:80/foo`
+* 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 entry point, and do **not** include it in `defaultEntryPoints`.
+Otherwise, you are likely to expose _all_ services via this entry point.

docs/user-guide/examples.md

@@ -335,68 +335,3 @@ providersThrottleDuration = "5s"
 [respondingTimeouts]
 idleTimeout = "360s"
 ```
-
-## 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:
-
-* Regular path: `http://hostname:80/foo`
-* 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 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 entry point
-* Enable `/ping` on a dedicated port
-
-### Enable ping health check on a regular entry point
-
-To proxy `/ping` from a regular entry point to the administration one without exposing the panel, do the following:
-
-```toml
-defaultEntryPoints = ["http"]
-
-[entryPoints]
-  [entryPoints.http]
-  address = ":80"
-
-[ping]
-entryPoint = "http"
-
-```
-
-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 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"]
-
-[entryPoints]
-  [entryPoints.http]
-  address = ":80"
-  [entryPoints.ping]
-  address = ":8082"
-
-[ping]
-entryPoint = "ping"
-```
-
-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 and health-check as follows:
-
-* Regular path: `http://hostname:80/foo`
-* 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 entry point, and do **not** include it in `defaultEntryPoints`.
-Otherwise, you are likely to expose _all_ services via this entry point.