diff --git a/README.md b/README.md
index d1dc0c4f4..df0f831bd 100644
--- a/README.md
+++ b/README.md
@@ -260,15 +260,18 @@ part of the process you need to customise:
   to disable unneeded services and clean the cache left by the package
   manager to reduce the size of the image.
 
-* first-boot.d: Runs inside the image before rc.local. Scripts from here are
-  good for doing per-instance configuration based on cloud metadata.
-
 * environment.d: Bash script snippets that are sourced before running scripts
   in each phase. Use this to set an environment variable for other hooks.
 
 * element-deps : A plain text, newline separated list of elements which will
   be added to the list of elements built into the image at image creation time.
 
+* first-boot.d: **DEPRECATED** Runs inside the image before
+  rc.local. Scripts from here are good for doing per-instance
+  configuration based on cloud metadata. **This will be removed in a
+  future release of diskimage-builder. The os-refresh-config element in
+  tripleo-image-elements is recommended as a replacement.**
+
 Ramdisk elements support the following files in their element directories:
 
 * binary-deps.d : text files listing executables required to be fed into the 
diff --git a/lib/common-functions b/lib/common-functions
index d75999215..8ac09e684 100644
--- a/lib/common-functions
+++ b/lib/common-functions
@@ -54,11 +54,43 @@ function save_image () {
     echo "Image file $1 created..."
 }
 
+function element_pre_check() {
+    local element_dir=$1
+    [ -d $element_dir ] || return 1
+    if [ -d $element_dir/first-boot.d ] ; then
+      first_boot_deprecated_message $element_dir
+    fi
+}
+
+_DISPLAYED_FIRST_BOOT_DEPRECATED=0
+function first_boot_deprecated_message() {
+    local element_dir=$1
+    echo "WARNING: first-boot.d found in $element_dir"
+    if [ $_DISPLAYED_FIRST_BOOT_DEPRECATED -eq 1 ] ; then
+        return
+    fi
+    echo "***********************************************************"
+    echo "*                                                         *"
+    echo "*                                                         *"
+    echo "*                                                         *"
+    echo "*                                                         *"
+    echo "* WARNING: first-boot.d is DEPRECATED, it will be removed *"
+    echo "* from diskimage-builder in a future release.             *"
+    echo "*                                                         *"
+    echo "*                                                         *"
+    echo "*                                                         *"
+    echo "*                                                         *"
+    echo "***********************************************************"
+    echo Pausing 10 seconds....
+    sleep 10
+    _DISPLAYED_FIRST_BOOT_DEPRECATED=1
+}
+
 function generate_hooks () {
   mkdir -p $TMP_HOOKS_PATH
   for _ELEMENT in $IMAGE_ELEMENT ; do
     for dir in $(echo $ELEMENTS_PATH | tr ":" " ") ; do
-       [ -d $dir/$_ELEMENT ] || continue
+      element_pre_check $dir/$_ELEMENT || continue
       cp -t $TMP_HOOKS_PATH -a $dir/$_ELEMENT/* ;
       break
     done