diff --git a/diskimage_builder/lib/common-functions b/diskimage_builder/lib/common-functions
index 407852dc7..a7f3666dc 100644
--- a/diskimage_builder/lib/common-functions
+++ b/diskimage_builder/lib/common-functions
@@ -338,8 +338,11 @@ function create_base () {
     fi
 
     # Configure Image
-    # Setup resolv.conf so we can chroot to install some packages
-    if [ -L $TMP_MOUNT_PATH/etc/resolv.conf ] || [ -f $TMP_MOUNT_PATH/etc/resolv.conf ] ; then
+
+    # Save resolv.conf as created by the initial install.  Note the
+    # .ORIG file is an exported interface -- it may be modified and we
+    # will copy it back in during finalisation of the image.
+    if [[ -e $TMP_MOUNT_PATH/etc/resolv.conf ]]; then
         sudo mv $TMP_MOUNT_PATH/etc/resolv.conf $TMP_MOUNT_PATH/etc/resolv.conf.ORIG
     fi
 
diff --git a/diskimage_builder/lib/img-functions b/diskimage_builder/lib/img-functions
index e43f73047..c861bdd5e 100644
--- a/diskimage_builder/lib/img-functions
+++ b/diskimage_builder/lib/img-functions
@@ -93,6 +93,13 @@ function run_d_in_target () {
 
 function finalise_base () {
     TARGET_ROOT=$TMP_MOUNT_PATH run_d cleanup
+
+    # Finalise resolv.conf
+    #
+    # NOTE(ianw): the /etc/resolv.conf.ORIG file is an
+    # external interface; elements might put a resolv.conf they
+    # want in the final image into this file.
+    #
     # In create_base() we replaced/created the initial resolv.conf
     # inside the image with a copy of the "outside" version so that
     # resolving during the build will work.
@@ -106,13 +113,14 @@ function finalise_base () {
         # so remove the old saved file
         sudo rm -f $TMP_MOUNT_PATH/etc/resolv.conf.ORIG
     else
-        # Remove the resolv.conf we created above
+        # Remove the resolv.conf we created and put the original (or
+        # perhaps modified) version back.
         sudo rm -f $TMP_MOUNT_PATH/etc/resolv.conf
-        # Move the original back
-        if [ -L $TMP_MOUNT_PATH/etc/resolv.conf.ORIG ] || [ -f $TMP_MOUNT_PATH/etc/resolv.conf.ORIG ] ; then
+        if [ -e $TMP_MOUNT_PATH/etc/resolv.conf.ORIG ]; then
             sudo mv $TMP_MOUNT_PATH/etc/resolv.conf.ORIG $TMP_MOUNT_PATH/etc/resolv.conf
         fi
     fi
+
     # Cleanup /tmp in the guest, so there is less cruft left there
     unmount_dir $TMP_MOUNT_PATH/tmp
     find $TMP_MOUNT_PATH/tmp -maxdepth 1 -mindepth 1 | xargs sudo rm -rf --one-file-system
diff --git a/doc/source/user_guide/building_an_image.rst b/doc/source/user_guide/building_an_image.rst
index 449cd115c..449b5a2d1 100644
--- a/doc/source/user_guide/building_an_image.rst
+++ b/doc/source/user_guide/building_an_image.rst
@@ -646,6 +646,29 @@ If tmpfs is not used, you will need enough room in /tmp to store two
 uncompressed cloud images. If tmpfs is used, you would still need /tmp space
 for one uncompressed cloud image and about 20% of that image for working files.
 
+Nameservers
+-----------
+
+To ensure elements can access the network, ``disk-image-create``
+replaces the ``/etc/resolv.conf`` within the chroot with a copy of the
+host's file early in the image creation process.
+
+The final ``/etc/resolv.conf`` can be controlled in a number of ways.
+If, during the build, the ``/etc/resolv.conf`` file within the chroot
+is replaced with a symlink, this will be retained in the final image
+[1]_.  If the file is marked immutable, it will also not be touched.
+
+.. [1] This somewhat odd case was added for installation of the
+       ``resolvconf`` package, which replaces ``/etc/resolv.conf``
+       with a symlink to it's version.  Depending on its contents, and
+       what comes after the installation in the build, this mostly
+       works.
+
+If you would like specific contents within the final
+``/etc/resolv.conf`` you can place them into
+``/etc/resolv.conf.ORIG`` during the build.  As one of the final
+steps, this file will be ``mv`` to ``/etc/resolv.conf``.
+
 
 Chosing an Architecture
 -----------------------