diff --git a/components/engine/docs/sources/reference/run.md b/components/engine/docs/sources/reference/run.md
index d594066ad0..8bf0d3633f 100644
--- a/components/engine/docs/sources/reference/run.md
+++ b/components/engine/docs/sources/reference/run.md
@@ -647,6 +647,12 @@ mechanism to communicate with a linked container by its alias:
 If you restart the source container (`servicename` in this case), the recipient
 container's `/etc/hosts` entry will be automatically updated.
 
+> **Note**:
+> Unlike host entries in the `/ets/hosts` file, IP addresses stored in the
+> environment variables are not automatically updated if the source container is
+> restarted. We recommend using the host entries in `/etc/hosts` to resolve the
+> IP address of linked containers.
+
 ## VOLUME (shared filesystems)
 
     -v=[]: Create a bind mount with: [host-dir]:[container-dir]:[rw|ro].
diff --git a/components/engine/docs/sources/userguide/dockerlinks.md b/components/engine/docs/sources/userguide/dockerlinks.md
index e2228cef00..e01604be45 100644
--- a/components/engine/docs/sources/userguide/dockerlinks.md
+++ b/components/engine/docs/sources/userguide/dockerlinks.md
@@ -232,6 +232,12 @@ command to list the specified container's environment variables.
 > container. Similarly, some daemons (such as `sshd`)
 > will scrub them when spawning shells for connection.
 
+> **Note**:
+> Unlike host entries in the [`/ets/hosts` file](#updating-the-etchosts-file),
+> IP addresses stored in the environment variables are not automatically updated
+> if the source container is restarted. We recommend using the host entries in
+> `/etc/hosts` to resolve the IP address of linked containers.
+
 You can see that Docker has created a series of environment variables with
 useful information about the source `db` container. Each variable is prefixed with
 `DB_`, which is populated from the `alias` you specified above. If the `alias`