Rework the port direction documentation

+ remove PUBLIC and PRIVATE keywords
+ add the <host_interface>
+ add the -expose flag through a simple link example
+ update the meaning of the EXPOSE command

docs/sources/commandline/cli.rst

@@ -636,26 +636,19 @@ using the container, but inside the current working directory.
 
 .. code-block:: bash
 
-    docker run -p 127.0.0.0::80 ubuntu bash
+    docker run -p 127.0.0.0:80:8080 ubuntu bash
 
-The ``-p`` flag now allows you to bind a port to a specific
+This binds port ``8080`` of the container to port ``80`` on 127.0.0.1 of the
-interface of the host machine.  In this example port ``80`` of the 
+host machine. :ref:`port_redirection` explains in detail how to manipulate ports
-container will have a dynamically allocated port bound to 127.0.0.1 
+in Docker.
-of the host.
-
-.. code-block:: bash
-
-    docker run -p 127.0.0.1:80:80 ubuntu bash
-
-This will bind port ``80`` of the container to port ``80`` on 127.0.0.1 of your
-host machine.
 
 .. code-block:: bash
 
     docker run -expose 80 ubuntu bash
 
-This will expose port ``80`` of the container for use within a link
+This exposes port ``80`` of the container for use within a link without
-without publishing the port to the host system's interfaces.  
+publishing the port to the host system's interfaces. :ref:`port_redirection`
+explains in detail how to manipulate ports in Docker.
 
 .. code-block:: bash
 
@@ -757,6 +750,3 @@ Show the version of the docker client, daemon, and latest released version.
     Usage: docker wait [OPTIONS] NAME
 
     Block until a container stops, then print its exit code.
-
-
-

docs/sources/use/builder.rst

@@ -174,10 +174,10 @@ override the default specified in CMD.
 
     ``EXPOSE <port> [<port>...]``
 
-The ``EXPOSE`` instruction sets ports to be publicly exposed when
+The ``EXPOSE`` instruction exposes ports for use within links. This is
-running the image. This is functionally equivalent to running ``docker
+functionally equivalent to running ``docker commit -run '{"PortSpecs":
-commit -run '{"PortSpecs": ["<port>", "<port2>"]}'`` outside the
+["<port>", "<port2>"]}'`` outside the builder. Refer to
-builder. Take a look at :ref:`port_redirection` for more information.
+:ref:`port_redirection` for detailed information.
 
 3.6 ENV
 -------

docs/sources/use/port_redirection.rst

@@ -8,29 +8,136 @@
 Port redirection
 ================
 
-Docker can redirect public TCP and UDP ports to your container, so it can be
+Interacting with a service is commonly done through a connection to a
-reached over the network.  Port redirection is done on ``docker run``
+port. When this service runs inside a container, one can connect to
-using the -p flag.
+the port after finding the IP address of the container as follows:
-
-A port redirect is specified as *PUBLIC:PRIVATE*, where TCP port
-*PUBLIC* will be redirected to TCP port *PRIVATE*. As a special case,
-the public port can be omitted, in which case a random public port
-will be allocated.
 
 .. code-block:: bash
 
-    # A random PUBLIC port is redirected to PRIVATE port 80 on the container
+    # Find IP address of container with ID <container_id>
-    sudo docker run -p 80 <image> <cmd>
+    docker inspect <container_id> | grep IPAddress | cut -d '"' -f 4
 
-    # PUBLIC port 80 is redirected to PRIVATE port 80
+However, this IP address is local to the host system and the container
-    sudo docker run -p 80:80 <image> <cmd>
+port is not reachable by the outside world. Furthermore, even if the
+port is used locally, e.g. by another container, this method is
+tedious as the IP address of the container changes every time it
+starts.
 
-To redirect a UDP port the redirection must be expressed as *PUBLIC:PRIVATE/udp*:
+Docker addresses these two problems and give a simple and robust way
+to access services running inside containers.
+
+To allow non-local clients to reach the service running inside the
+container, Docker provide ways to bind the container port to an
+interface of the host system. To simplify communication between
+containers, Docker provides the linking mechanism.
+
+Binding a port to an host interface
+-----------------------------------
+
+To bind a port of the container to a specific interface of the host
+system, use the ``-p`` parameter of the ``docker run`` command:
 
 .. code-block:: bash
 
-    # PUBLIC port 5300 is redirected to the PRIVATE port 53 using UDP
+    # General syntax
-    sudo docker run -p 5300:53/udp <image> <cmd>
+    docker run -p [([<host_interface>:[host_port]])|(<host_port>):]<container_port>[/udp] <image> <cmd>
 
-Default port redirects can be built into a container with the
+When no host interface is provided, the port is bound to all available
-``EXPOSE`` build command.
+interfaces of the host machine (aka INADDR_ANY, or 0.0.0.0).When no host port is
+provided, one is dynamically allocated. The possible combinations of options for
+TCP port are the following:
+
+.. code-block:: bash
+
+    # Bind TCP port 8080 of the container to TCP port 80 on 127.0.0.1 of the host machine.
+    docker run -p 127.0.0.1:80:8080 <image> <cmd>
+
+    # Bind TCP port 8080 of the container to a dynamically allocated TCP port on 127.0.0.1 of the host machine.
+    docker run -p 127.0.0.1::8080 <image> <cmd>
+
+    # Bind TCP port 8080 of the container to TCP port 80 on all available interfaces of the host machine.
+    docker run -p 80:8080 <image> <cmd>
+
+    # Bind TCP port 8080 of the container to a dynamically allocated TCP port on all available interfaces of the host machine.
+    docker run -p 8080 <image> <cmd>
+
+UDP ports can also be bound by adding a trailing ``/udp``. All the
+combinations described for TCP work. Here is only one example:
+
+.. code-block:: bash
+
+    # Bind UDP port 5353 of the container to UDP port 53 on 127.0.0.1 of the host machine.
+    docker run -p 127.0.0.1:53:5353/udp <image> <cmd>
+
+The command ``docker port`` lists the interface and port on the host
+machine bound to a given container port. It is useful when using
+dynamically allocated ports:
+
+.. code-block:: bash
+
+   # Bind to a dynamically allocated port
+   docker run -p 127.0.0.1::8080 -name dyn-bound <image> <cmd>
+
+   # Lookup the actual port
+   docker port dyn-bound 8080
+   127.0.0.1:49160
+
+
+Linking a container
+-------------------
+
+Communication between two containers can also be established in a
+docker-specific way called linking.
+
+To briefly present the concept of linking, let us consider two
+containers: ``server``, containing the service, and ``client``,
+accessing the service.  Once ``server`` is running, ``client`` is
+started and links to server. Linking sets environment variables in
+``client`` giving it some information about ``server``. In this sense,
+linking is a method of service discovery.
+
+Let us now get back to our topic of interest; communication between
+the two containers. We mentioned that the tricky part about this
+communication was that the IP address of ``server`` was not
+fixed. Therefore, some of the environment variables are going to be
+used to inform ``client`` about this IP address. This process called
+exposure, is possible because ``client`` is started after ``server``
+has been started.
+
+Here is a full example. On ``server``, the port of interest is
+exposed. The exposure is done either through the ``-expose`` parameter
+to the ``docker run`` command, or the ``EXPOSE`` build command in a
+Dockerfile:
+
+.. code-block:: bash
+
+    # Expose port 80
+    docker run -expose 80 -name server <image> <cmd>
+
+The ``client`` then links to the ``server``:
+
+.. code-block:: bash
+
+    # Link
+    docker run -name client -link server:linked-server <image> <cmd>
+
+``client`` locally refers to ``server`` as ``linked-server``. The
+following environment variables, among others, are available on
+``client``:
+
+.. code-block:: bash
+
+    # The default protocol, ip, and port of the service running in the container
+    LINKED-SERVER_PORT=tcp://172.17.0.8:80
+
+    # A specific protocol, ip, and port of various services
+    LINKED-SERVER_PORT_80_TCP=tcp://172.17.0.8:80
+    LINKED-SERVER_PORT_80_TCP_PROTO=tcp
+    LINKED-SERVER_PORT_80_TCP_ADDR=172.17.0.8
+    LINKED-SERVER_PORT_80_TCP_PORT=80
+
+This tells ``client`` that a service is running on port 80 of
+``server`` and that ``server`` is accessible at the IP address
+172.17.0.8
+
+Note: Using the ``-p`` parameter also exposes the port..