@@ -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:

 ~~~~~~~~~

@@ -621,58 +621,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:

@@ -713,7 +706,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:

@@ -758,6 +751,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.

-

-

-

@@ -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:

@@ -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..