Merge pull request #23359 from londoncalling/docker-engine-overview

re-doing Docker Engine overview topics for v.1.12
Upstream-commit: 1164f917faa46e0178dd5050a524a635ea849386
Component: engine

components/engine/docs/reference/api/docker_remote_api_v1.18.md

@@ -15,7 +15,7 @@ weight = 3
 
  - The Remote API has replaced `rcli`.
  - The daemon listens on `unix:///var/run/docker.sock` but you can
-   [Bind Docker to another host/port or a Unix socket](../../quickstart.md#bind-docker-to-another-host-port-or-a-unix-socket).
+   [Bind Docker to another host/port or a Unix socket](../commandline/dockerd.md#bind-docker-to-another-host-port-or-a-unix-socket).
  - The API tends to be REST, but for some complex commands, like `attach`
    or `pull`, the HTTP connection is hijacked to transport `STDOUT`,
    `STDIN` and `STDERR`.

components/engine/docs/reference/api/docker_remote_api_v1.19.md

@@ -15,7 +15,7 @@ weight = 2
 
  - The Remote API has replaced `rcli`.
  - The daemon listens on `unix:///var/run/docker.sock` but you can
-   [Bind Docker to another host/port or a Unix socket](../../quickstart.md#bind-docker-to-another-host-port-or-a-unix-socket).
+   [Bind Docker to another host/port or a Unix socket](../commandline/dockerd.md#bind-docker-to-another-host-port-or-a-unix-socket).
  - The API tends to be REST. However, for some complex commands, like `attach`
    or `pull`, the HTTP connection is hijacked to transport `stdout`,
    `stdin` and `stderr`.

components/engine/docs/reference/api/docker_remote_api_v1.20.md

@@ -15,7 +15,7 @@ weight = 1
 
  - The Remote API has replaced `rcli`.
  - The daemon listens on `unix:///var/run/docker.sock` but you can
-   [Bind Docker to another host/port or a Unix socket](../../quickstart.md#bind-docker-to-another-host-port-or-a-unix-socket).
+   [Bind Docker to another host/port or a Unix socket](../commandline/dockerd.md#bind-docker-to-another-host-port-or-a-unix-socket).
  - The API tends to be REST. However, for some complex commands, like `attach`
    or `pull`, the HTTP connection is hijacked to transport `stdout`,
    `stdin` and `stderr`.
@@ -1362,12 +1362,12 @@ or being killed.
 
 Query Parameters:
 
--   **dockerfile** - Path within the build context to the Dockerfile. This is 
+-   **dockerfile** - Path within the build context to the Dockerfile. This is
         ignored if `remote` is specified and points to an individual filename.
 -   **t** – A repository name (and optionally a tag) to apply to
         the resulting image in case of success.
--   **remote** – A Git repository URI or HTTP/HTTPS URI build source. If the 
-        URI specifies a filename, the file's contents are placed into a file 
+-   **remote** – A Git repository URI or HTTP/HTTPS URI build source. If the
+        URI specifies a filename, the file's contents are placed into a file
 		called `Dockerfile`.
 -   **q** – Suppress verbose build output.
 -   **nocache** – Do not use the cache when building the image.
@@ -2338,7 +2338,7 @@ from **200 OK** to **101 UPGRADED** and resends the same headers.
 
 ## 3.3 CORS Requests
 
-To set cross origin requests to the remote api please give values to 
+To set cross origin requests to the remote api please give values to
 `--api-cors-header` when running Docker in daemon mode. Set * (asterisk) allows all,
 default or blank means CORS disabled
 

components/engine/docs/reference/api/docker_remote_api_v1.21.md

@@ -15,7 +15,7 @@ weight=-2
 
  - The Remote API has replaced `rcli`.
  - The daemon listens on `unix:///var/run/docker.sock` but you can
-   [Bind Docker to another host/port or a Unix socket](../../quickstart.md#bind-docker-to-another-host-port-or-a-unix-socket).
+   [Bind Docker to another host/port or a Unix socket](../commandline/dockerd.md#bind-docker-to-another-host-port-or-a-unix-socket).
  - The API tends to be REST. However, for some complex commands, like `attach`
    or `pull`, the HTTP connection is hijacked to transport `stdout`,
    `stdin` and `stderr`.

components/engine/docs/reference/api/docker_remote_api_v1.22.md

@@ -15,7 +15,7 @@ weight=-3
 
  - The Remote API has replaced `rcli`.
  - The daemon listens on `unix:///var/run/docker.sock` but you can
-   [Bind Docker to another host/port or a Unix socket](../../quickstart.md#bind-docker-to-another-host-port-or-a-unix-socket).
+   [Bind Docker to another host/port or a Unix socket](../commandline/dockerd.md#bind-docker-to-another-host-port-or-a-unix-socket).
  - The API tends to be REST. However, for some complex commands, like `attach`
    or `pull`, the HTTP connection is hijacked to transport `stdout`,
    `stdin` and `stderr`.

components/engine/docs/reference/api/docker_remote_api_v1.23.md

@@ -15,7 +15,7 @@ weight=-4
 
  - The Remote API has replaced `rcli`.
  - The daemon listens on `unix:///var/run/docker.sock` but you can
-   [Bind Docker to another host/port or a Unix socket](../../quickstart.md#bind-docker-to-another-host-port-or-a-unix-socket).
+   [Bind Docker to another host/port or a Unix socket](../commandline/dockerd.md#bind-docker-to-another-host-port-or-a-unix-socket).
  - The API tends to be REST. However, for some complex commands, like `attach`
    or `pull`, the HTTP connection is hijacked to transport `stdout`,
    `stdin` and `stderr`.

components/engine/docs/reference/api/docker_remote_api_v1.24.md

@@ -15,7 +15,7 @@ weight=-5
 
  - The Remote API has replaced `rcli`.
  - The daemon listens on `unix:///var/run/docker.sock` but you can
-   [Bind Docker to another host/port or a Unix socket](../../quickstart.md#bind-docker-to-another-host-port-or-a-unix-socket).
+   [Bind Docker to another host/port or a Unix socket](../commandline/dockerd.md#bind-docker-to-another-host-port-or-a-unix-socket).
  - The API tends to be REST. However, for some complex commands, like `attach`
    or `pull`, the HTTP connection is hijacked to transport `stdout`,
    `stdin` and `stderr`.

components/engine/docs/reference/commandline/dockerd.md

@@ -139,6 +139,68 @@ The Docker client will honor the `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY`
 environment variables (or the lowercase versions thereof). `HTTPS_PROXY` takes
 precedence over `HTTP_PROXY`.
 
+### Bind Docker to another host/port or a Unix socket
+
+> **Warning**:
+> Changing the default `docker` daemon binding to a
+> TCP port or Unix *docker* user group will increase your security risks
+> by allowing non-root users to gain *root* access on the host. Make sure
+> you control access to `docker`. If you are binding
+> to a TCP port, anyone with access to that port has full Docker access;
+> so it is not advisable on an open network.
+
+With `-H` it is possible to make the Docker daemon to listen on a
+specific IP and port. By default, it will listen on
+`unix:///var/run/docker.sock` to allow only local connections by the
+*root* user. You *could* set it to `0.0.0.0:2375` or a specific host IP
+to give access to everybody, but that is **not recommended** because
+then it is trivial for someone to gain root access to the host where the
+daemon is running.
+
+Similarly, the Docker client can use `-H` to connect to a custom port.
+The Docker client will default to connecting to `unix:///var/run/docker.sock`
+on Linux, and `tcp://127.0.0.1:2376` on Windows.
+
+`-H` accepts host and port assignment in the following format:
+
+    tcp://[host]:[port][path] or unix://path
+
+For example:
+
+-   `tcp://` -> TCP connection to `127.0.0.1` on either port `2376` when TLS encryption
+    is on, or port `2375` when communication is in plain text.
+-   `tcp://host:2375` -> TCP connection on
+    host:2375
+-   `tcp://host:2375/path` -> TCP connection on
+    host:2375 and prepend path to all requests
+-   `unix://path/to/socket` -> Unix socket located
+    at `path/to/socket`
+
+`-H`, when empty, will default to the same value as
+when no `-H` was passed in.
+
+`-H` also accepts short form for TCP bindings:
+
+    `host:` or `host:port` or `:port`
+
+Run Docker in daemon mode:
+
+    $ sudo <path to>/dockerd -H 0.0.0.0:5555 &
+
+Download an `ubuntu` image:
+
+    $ docker -H :5555 pull ubuntu
+
+You can use multiple `-H`, for example, if you want to listen on both
+TCP and a Unix socket
+
+    # Run docker in daemon mode
+    $ sudo <path to>/dockerd -H tcp://127.0.0.1:2375 -H unix:///var/run/docker.sock &
+    # Download an ubuntu image, use default Unix socket
+    $ docker pull ubuntu
+    # OR use the TCP port
+    $ docker -H tcp://127.0.0.1:2375 pull ubuntu
+
 ### Daemon storage-driver option
 
 The Docker daemon has support for several different image layer storage
@@ -529,7 +591,7 @@ can specify default container isolation technology with this, for example:
 
 Will make `hyperv` the default isolation technology on Windows. If no isolation
 value is specified on daemon start, on Windows client, the default is
-`hyperv`, and on Windows server, the default is `process`. 
+`hyperv`, and on Windows server, the default is `process`.
 
 ## Daemon DNS options