Merge pull request #8507 from duglin/Issue3087

Add some docs about which env vars are defined in new containers

docs/sources/reference/run.md

@@ -428,9 +428,48 @@ client container to help indicate which interface and port to use.
 
 ## ENV (Environment Variables)
 
-The operator can **set any environment variable** in the container by
-using one or more `-e` flags, even overriding those already defined by
-the developer with a Dockerfile `ENV`:
+When a new container is created, Docker will set the following environment
+variables automatically:
+
+<table width=100%>
+ <tr style="background-color:#C0C0C0">
+  <td> <b>Variable</b> </td>
+  <td style="padding-left:10px"> <b>Value</b> </td>
+ </tr>
+ <tr>
+  <td> <code>HOME</code> </td>
+  <td style="padding-left:10px">
+    Set based on the value of <code>USER</code>
+  </td>
+ </tr>
+ <tr style="background-color:#E8E8E8">
+  <td valign=top> <code>HOSTNAME</code> </td>
+  <td style="padding-left:10px"> 
+    The hostname associated with the container
+  </td>
+ </tr>
+ <tr>
+  <td valign=top> <code>PATH</code> </td>
+  <td style="padding-left:10px"> 
+    Includes popular directories, such as :<br>
+    <code>/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin</code>
+  </td>
+ <tr style="background-color:#E8E8E8">
+  <td valign=top> <code>TERM</code> </td>
+  <td style="padding-left:10px"> 
+    <code>xterm</code> if the container is allocated a psuedo-TTY 
+  </td>
+ </tr>
+</table>
+
+The container may also include environment variables defined
+as a result of the container being linked with another container. See
+the [*Container Links*](/userguide/dockerlinks/#container-linking)
+section for more details.
+
+Additionally, the operator can **set any environment variable** in the 
+container by using one or more `-e` flags, even overriding those mentioned 
+above, or already defined by the developer with a Dockerfile `ENV`:
 
     $ sudo docker run -e "deep=purple" --rm ubuntu /bin/bash -c export
     declare -x HOME="/"