pull in the rework of /var/lib/cloud.

- /var/lib/cloud is redesigned, and its layout now described in
  doc/var-lib-cloud.txt.
  The big plus point of this was to get instance specific data
  into /var/lib/cloud/instances, so that data could easily be purged.

  A symlink /var/lib/cloud/instance -> /var/lib/cloud/instances/<current_id>
  is maintained.

- Also, now run scripts in /var/lib/cloud/scripts/
   per-once
   per-boot
   per-instance

- bugs addressed:
  - LP: #704509

1 files changed, 56 insertions, 0 deletions

diff --git a/doc/var-lib-cloud.txt b/doc/var-lib-cloud.txt
new file mode 100644
index 00000000..2a1acd2b
--- /dev/null
+++ b/doc/var-lib-cloud.txt
@@ -0,0 +1,56 @@
+/var/lib/cloud has the following structure:
+  - scripts/
+      per-instance/
+      per-boot/
+      per-once/
+
+    files in these directories will be run by 'run-parts' once per
+    instance, once per boot, and once per *ever*.
+
+  - seed/
+     <datasource>/
+        sys-user-data
+        user-data
+        meta-data
+
+     The 'seed/' directory allows you to seed a specific datasource
+     For example, to seed the 'nocloud' datasource you would need to
+     populate 
+       seed/nocloud/user-data
+       seed/nocloud/meta-data
+
+  - instance -> instances/i-abcde
+    This is a symlink to the current instance/<instance-id> directory
+    created/updated on boot
+  - instances/
+      i-abcdefgh/
+         scripts/ # all scripts in scripts are per-instance
+         sem/
+            config-puppet
+            config-ssh
+            set-hostname
+         cloud-config.txt
+         user-data.txt
+         user-data.txt.i
+         obj.pkl
+         handlers/
+         data/  # just a per-instance data location to be used
+          
+  - sem/
+      scripts.once
+    These are the cloud-specific semaphores.  The only thing that
+    would go here are files to mark that a "per-once" script
+    has run.
+
+  - handlers/
+      "persistent" handlers (not per-instance).  Same as handlers
+      from user-data, just will be cross-instance id
+
+  - data/
+      this is a persistent data location.  cloud-init won't really
+      use it, but something else (a handler or script could)
+
+to clear out the current instance's data as if to force a "new run" on reboot
+do:
+  ( cd /var/lib/cloud/instance && sudo rm -Rf * )
+