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

@@ -41,7 +41,7 @@ To stop a container, use ``docker stop``
 To kill the container, use ``docker kill``
 
 .. _cli_attach_examples:
- 
+
 Examples:
 ~~~~~~~~~
 
@@ -55,8 +55,8 @@ Examples:
      Mem:    373572k total,   355560k used,    18012k free,    27872k buffers
      Swap:   786428k total,        0k used,   786428k free,   221740k cached
 
-     PID USER      PR  NI  VIRT  RES  SHR S %CPU %MEM    TIME+  COMMAND            
-      1 root      20   0 17200 1116  912 R    0  0.3   0:00.03 top                
+     PID USER      PR  NI  VIRT  RES  SHR S %CPU %MEM    TIME+  COMMAND
+      1 root      20   0 17200 1116  912 R    0  0.3   0:00.03 top
 
       top - 02:05:55 up  3:05,  0 users,  load average: 0.01, 0.02, 0.05
       Tasks:   1 total,   1 running,   0 sleeping,   0 stopped,   0 zombie
@@ -64,8 +64,8 @@ Examples:
       Mem:    373572k total,   355244k used,    18328k free,    27872k buffers
       Swap:   786428k total,        0k used,   786428k free,   221776k cached
 
-        PID USER      PR  NI  VIRT  RES  SHR S %CPU %MEM    TIME+  COMMAND            
-	    1 root      20   0 17208 1144  932 R    0  0.3   0:00.03 top                
+        PID USER      PR  NI  VIRT  RES  SHR S %CPU %MEM    TIME+  COMMAND
+	    1 root      20   0 17208 1144  932 R    0  0.3   0:00.03 top
 
 
       top - 02:05:58 up  3:06,  0 users,  load average: 0.01, 0.02, 0.05
@@ -74,9 +74,9 @@ Examples:
       Mem:    373572k total,   355780k used,    17792k free,    27880k buffers
       Swap:   786428k total,        0k used,   786428k free,   221776k cached
 
-      PID USER      PR  NI  VIRT  RES  SHR S %CPU %MEM    TIME+  COMMAND            
-           1 root      20   0 17208 1144  932 R    0  0.3   0:00.03 top                
-     ^C$ 
+      PID USER      PR  NI  VIRT  RES  SHR S %CPU %MEM    TIME+  COMMAND
+           1 root      20   0 17208 1144  932 R    0  0.3   0:00.03 top
+     ^C$
      $ sudo docker stop $ID
 
 .. _cli_build:
@@ -157,7 +157,7 @@ by using the ``git://`` schema.
 
       -m="": Commit message
       -author="": Author (eg. "John Hannibal Smith <hannibal@a-team.com>"
-      -run="": Configuration to be applied when the image is launched with `docker run`. 
+      -run="": Configuration to be applied when the image is launched with `docker run`.
                (ex: '{"Cmd": ["cat", "/world"], "PortSpecs": ["22"]}')
 
 Full -run example (multiline is ok within a single quote ``'``)
@@ -239,7 +239,7 @@ Shell 1: Listening for events
 .............................
 
 .. code-block:: bash
-    
+
     $ sudo docker events
 
 Shell 2: Start and Stop a Container
@@ -405,7 +405,7 @@ Insert file from github
     Usage: docker kill CONTAINER [CONTAINER...]
 
     Kill a running container (Send SIGKILL)
-    
+
 The main process inside the container will be sent SIGKILL.
 
 .. _cli_login:
@@ -515,7 +515,7 @@ The main process inside the container will be sent SIGKILL.
 
     Remove one or more containers
         -link="": Remove the link instead of the actual container
- 
+
 
 Examples:
 ~~~~~~~~~
@@ -620,58 +620,51 @@ use-cases, like running Docker within Docker.
 
    docker  run -w /path/to/dir/ -i -t  ubuntu pwd
 
-The ``-w`` lets the command being executed inside directory given, 
-here /path/to/dir/. If the path does not exists it is created inside the 
+The ``-w`` lets the command being executed inside directory given,
+here /path/to/dir/. If the path does not exists it is created inside the
 container.
 
 .. code-block:: bash
 
    docker  run  -v `pwd`:`pwd` -w `pwd` -i -t  ubuntu pwd
 
-The ``-v`` flag mounts the current working directory into the container. 
-The ``-w`` lets the command being executed inside the current 
+The ``-v`` flag mounts the current working directory into the container.
+The ``-w`` lets the command being executed inside the current
 working directory, by changing into the directory to the value
 returned by ``pwd``. So this combination executes the command
 using the container, but inside the current working directory.
 
 .. code-block:: bash
 
-    docker run -p 127.0.0.0::80 ubuntu bash
-
-The ``-p`` flag now allows you to bind a port to a specific
-interface of the host machine.  In this example port ``80`` of the 
-container will have a dynamically allocated port bound to 127.0.0.1 
-of the host.
-
-.. code-block:: bash
-
-    docker run -p 127.0.0.1:80:80 ubuntu bash
+    docker run -p 127.0.0.0:80:8080 ubuntu bash
 
-This will bind port ``80`` of the container to port ``80`` on 127.0.0.1 of your
-host machine.
+This binds port ``8080`` of the container to port ``80`` on 127.0.0.1 of the
+host machine. :ref:`port_redirection` explains in detail how to manipulate ports
+in Docker.
 
 .. code-block:: bash
 
     docker run -expose 80 ubuntu bash
 
-This will expose port ``80`` of the container for use within a link
-without publishing the port to the host system's interfaces.  
+This exposes port ``80`` of the container for use within a link without
+publishing the port to the host system's interfaces. :ref:`port_redirection`
+explains in detail how to manipulate ports in Docker.
 
 .. code-block:: bash
 
     docker run -name console -t -i ubuntu bash
 
-This will create and run a new container with the container name 
+This will create and run a new container with the container name
 being ``console``.
 
 .. code-block:: bash
 
     docker run -link /redis:redis -name console ubuntu bash
 
-The ``-link`` flag will link the container named ``/redis`` into the 
+The ``-link`` flag will link the container named ``/redis`` into the
 newly created container with the alias ``redis``.  The new container
 can access the network and environment of the redis container via
-environment variables.  The ``-name`` flag will assign the name ``console`` 
+environment variables.  The ``-name`` flag will assign the name ``console``
 to the newly created container.
 
 .. _cli_search:
@@ -712,7 +705,7 @@ to the newly created container.
     Stop a running container (Send SIGTERM, and then SIGKILL after grace period)
 
       -t=10: Number of seconds to wait for the container to stop before killing it.
-      
+
 The main process inside the container will receive SIGTERM, and after a grace period, SIGKILL
 
 .. _cli_tag:
@@ -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
-running the image. This is functionally equivalent to running ``docker
-commit -run '{"PortSpecs": ["<port>", "<port2>"]}'`` outside the
-builder. Take a look at :ref:`port_redirection` for more information.
+The ``EXPOSE`` instruction exposes ports for use within links. This is
+functionally equivalent to running ``docker commit -run '{"PortSpecs":
+["<port>", "<port2>"]}'`` outside the builder. Refer to
+:ref:`port_redirection` for detailed information.
 
 3.6 ENV
 -------
@@ -243,7 +243,7 @@ The copy obeys the following rules:
   considered a regular file and the contents of ``<src>`` will be
   written at ``<dest>``.
 * If ``<dest>`` doesn't exist, it is created along with all missing
-  directories in its path. 
+  directories in its path.
 
 .. _entrypoint_def:
 

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
-reached over the network.  Port redirection is done on ``docker run``
-using the -p flag.
+Interacting with a service is commonly done through a connection to a
+port. When this service runs inside a container, one can connect to
+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
+
+    # Find IP address of container with ID <container_id>
+    docker inspect <container_id> | grep IPAddress | cut -d '"' -f 4
+
+However, this IP address is local to the host system and the container
+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.
+
+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
 
-    # A random PUBLIC port is redirected to PRIVATE port 80 on the container
-    sudo docker run -p 80 <image> <cmd>
+    # General syntax
+    docker run -p [([<host_interface>:[host_port]])|(<host_port>):]<container_port>[/udp] <image> <cmd>
+
+When no host interface is provided, the port is bound to all available
+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
 
-    # PUBLIC port 80 is redirected to PRIVATE port 80
-    sudo docker run -p 80:80 <image> <cmd>
+    # 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>
 
-To redirect a UDP port the redirection must be expressed as *PUBLIC:PRIVATE/udp*:
+    # 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
 
-    # PUBLIC port 5300 is redirected to the PRIVATE port 53 using UDP
-    sudo docker run -p 5300:53/udp <image> <cmd>
+    # 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
 
-Default port redirects can be built into a container with the
-``EXPOSE`` build command.
+Note: Using the ``-p`` parameter also exposes the port..