Windows: some documentation about networking

Prompted by docker/for-mac#2705 (and
docker/for-win#1855).

Signed-off-by: Akim Demaille <akim.demaille@docker.com>

docker-for-windows/networking.md

@@ -0,0 +1,138 @@
+---
+description: Networking
+keywords: windows, networking
+title: Networking features in Docker for Windows
+---
+{% assign Arch = 'Windows' %}
+
+Docker for {{Arch}} provides several networking features to make it easier to
+use.
+
+## Features
+
+### VPN Passthrough
+
+Docker for {{Arch}}'s networking can work when attached to a VPN. To do this,
+Docker for {{Arch}} intercepts traffic from the containers and injects it into
+Windows as if it originated from the Docker application.
+
+### Port Mapping
+
+When you run a container with the `-p` argument, for example:
+
+```
+$ docker run -p 80:80 -d nginx
+```
+
+Docker for {{Arch}} makes whatever is running on port 80 in the container (in
+this case, `nginx`) available on port 80 of `localhost`. In this example, the
+host and container ports are the same. What if you need to specify a different
+host port? If, for example, you already have something running on port 80 of
+your host machine, you can connect the container to a different port:
+
+```
+$ docker run -p 8000:80 -d nginx
+```
+
+Now, connections to `localhost:8000` are sent to port 80 in the container. The
+syntax for `-p` is `HOST_PORT:CLIENT_PORT`.
+
+<!--
+### FIXME: HTTP/HTTPS Proxy Support
+
+To enable the proxy, go to the settings page and...
+
+![macOS Proxy Settings](images/proxy-settings.png)
+
+When you start a container, your proxy settings propagate into
+the containers. For example:
+
+```
+$ docker run -it alpine env
+PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+HOSTNAME=b7edf988b2b5
+TERM=xterm
+HOME=/root
+HTTP_PROXY=http://proxy.example.com:3128
+http_proxy=http://proxy.example.com:3128
+no_proxy=*.local, 169.254/16
+```
+
+You can see from the above output that the `HTTP_PROXY`, `http_proxy`, and
+`no_proxy` environment variables are set. When your proxy configuration changes,
+Docker restarts automatically to pick up the new settings. If you have
+containers that you wish to keep running across restarts, you should consider
+using [restart policies](/engine/reference/run/#restart-policies-restart).
+
+-->
+
+## Known limitations, use cases, and workarounds
+
+Following is a summary of current limitations on the Docker for {{Arch}}
+networking stack, along with some ideas for workarounds.
+
+### There is no docker0 bridge on {{Arch}}
+
+Because of the way networking is implemented in Docker for {{Arch}}, you cannot
+see a `docker0` interface in macOS.  This interface is actually within the
+virtual machine.
+
+### I cannot ping my containers
+
+Docker for Windows can't route traffic to Linux containers.  However, you can
+ping the Windows Containers.
+
+### Per-container IP addressing is not possible
+
+The docker (Linux) bridge network is not reachable from the Windows host.
+However, it works with Windows Containers.
+
+### Use cases and workarounds
+
+There are two scenarios that the above limitations affect:
+
+#### I want to connect from a container to a service on the host
+
+The host has a changing IP address (or none if you have no network access). From
+18.03 onwards our recommendation is to connect to the special Mac-only DNS name
+`host.docker.internal`, which resolves to the internal IP address used by the
+host.
+
+The gateway is also reachable as `gateway.docker.internal`.
+
+#### I want to connect to a container from the Windows
+
+Port forwarding works for `localhost`; `--publish`, `-p`, or `-P` all work.
+Ports exposed from Linux are forwarded to the host.
+
+Our current recommendation is to publish a port, or to connect from another
+container. This is what you need to do even on Linux if the container is on an
+overlay network, not a bridge network, as these are not routed.
+
+The command to run the `nginx` webserver shown in [Getting
+Started](/docker-for-mac/index.md#explore-the-application-and-run-examples) is
+an example of this.
+
+```bash
+$ docker run -d -p 80:80 --name webserver nginx
+```
+
+To clarify the syntax, the following two commands both expose port `80` on the
+container to port `8000` on the host:
+
+```bash
+$ docker run --publish 8000:80 --name webserver nginx
+
+$ docker run -p 8000:80 --name webserver nginx
+```
+
+To expose all ports, use the `-P` flag. For example, the following command
+starts a container (in detached mode) and the `-P` exposes all ports on the
+container to random ports on the host.
+
+```bash
+$ docker run -d -P --name webserver nginx
+```
+
+See the [run command](/engine/reference/commandline/run.md) for more details on
+publish options used with `docker run`.