Formalise saving of /etc/resolv.conf

systemd-resolved has a new behaviour in bionic, in that if there is no
/etc/resolv.conf file when it installs, it assumes it is a fresh
system and makes /etc/resolf.conf a symlink into its compatability
files.

dib ends up saving & restoring whatever /etc/resolv.conf we have after
the inital chroot creation, which may not be what we want -- in the
above case it restores the system-resolved symlink.  For
openstack-infra, we use unbound and want simply "127.0.0.1" in a
/etc/resolv.conf file [1].

Formalise the ability to save specific contents into the final image.
Add documentation, and a note in the code that it's an external
interface.

I would have preferred to namespace the .ORIG file with DIB_ or
similar, but this unofficial interface has already escaped into the
wild.  Leave it as is for simplicity.

[1] Note that systemd-resolved will obey /etc/resolv.conf as you would
expect, if file exists.

Change-Id: Ie0e97d8072e2b21a54b053fa6fb07b62960c686d

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
 

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 [ -e $TMP_MOUNT_PATH/etc/resolv.conf.ORIG ]; then
-        if [ -L $TMP_MOUNT_PATH/etc/resolv.conf.ORIG ] || [ -f $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

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
 -----------------------