Merge pull request #4057 from SvenDowideit/add-P-docs

add a little more information about the docker run -P option

docs/sources/reference/commandline/cli.rst

@@ -1088,6 +1088,10 @@ is, ``docker run`` is equivalent to the API ``/containers/create`` then
 The ``docker run`` command can be used in combination with ``docker commit`` to
 :ref:`change the command that a container runs <cli_commit_examples>`.
 
+See :ref:`port_redirection` for more detailed information about the ``--expose``, 
+``-p``, ``-P`` and ``--link`` parameters, and :ref:`working_with_links_names` for 
+specific examples using ``--link``.
+
 Known Issues (run -volumes-from)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/sources/use/port_redirection.rst

@@ -31,6 +31,15 @@ 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.
 
+Auto map all exposed ports on the host
+-------------------------------------
+
+To bind all the exposed container ports to the host automatically, use 
+``docker run -P <imageid>``.  The mapped host ports will be auto-selected 
+from a pool of unused ports (49000..49900), and you will need to use 
+``docker ps``, ``docker inspect <container_id>``  or 
+``docker port <container_id> <port>`` to determine what they are.
+
 Binding a port to a host interface
 -----------------------------------