From c0e51a8f27defe3d4dde0b5805d3801cf25a6ce2 Mon Sep 17 00:00:00 2001 From: Nicolas Dudebout Date: Thu, 31 Oct 2013 00:10:29 -0400 Subject: [PATCH] Rework the port direction documentation + remove PUBLIC and PRIVATE keywords + add the + add the -expose flag through a simple link example + update the meaning of the EXPOSE command --- docs/sources/commandline/cli.rst | 64 +++++------- docs/sources/use/builder.rst | 10 +- docs/sources/use/port_redirection.rst | 141 ++++++++++++++++++++++---- 3 files changed, 156 insertions(+), 59 deletions(-) diff --git a/docs/sources/commandline/cli.rst b/docs/sources/commandline/cli.rst index c6579da355..f3f9e7752c 100644 --- a/docs/sources/commandline/cli.rst +++ b/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 " - -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 + docker run -p 127.0.0.0:80:8080 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 - -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. - - - diff --git a/docs/sources/use/builder.rst b/docs/sources/use/builder.rst index 4341826f45..d1747c3fb3 100644 --- a/docs/sources/use/builder.rst +++ b/docs/sources/use/builder.rst @@ -174,10 +174,10 @@ override the default specified in CMD. ``EXPOSE [...]`` -The ``EXPOSE`` instruction sets ports to be publicly exposed when -running the image. This is functionally equivalent to running ``docker -commit -run '{"PortSpecs": ["", ""]}'`` 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": +["", ""]}'`` 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 ```` will be written at ````. * If ```` doesn't exist, it is created along with all missing - directories in its path. + directories in its path. .. _entrypoint_def: diff --git a/docs/sources/use/port_redirection.rst b/docs/sources/use/port_redirection.rst index 5c321d429d..adce1cba61 100644 --- a/docs/sources/use/port_redirection.rst +++ b/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. - -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. +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: .. code-block:: bash - # A random PUBLIC port is redirected to PRIVATE port 80 on the container - sudo docker run -p 80 + # Find IP address of container with ID + docker inspect | grep IPAddress | cut -d '"' -f 4 - # PUBLIC port 80 is redirected to PRIVATE port 80 - sudo docker run -p 80:80 +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. -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 - sudo docker run -p 5300:53/udp + # General syntax + docker run -p [([:[host_port]])|():][/udp] -Default port redirects can be built into a container with the -``EXPOSE`` build command. +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 + + # 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 + + # 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 + + # Bind TCP port 8080 of the container to TCP port 80 on all available interfaces of the host machine. + docker run -p 80:8080 + + # 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 + +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 + +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 + + # 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 + +The ``client`` then links to the ``server``: + +.. code-block:: bash + + # Link + docker run -name client -link server:linked-server + +``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..