Rebase on upstream

7 files changed, 153 insertions, 26 deletions

diff --git a/doc/examples/cloud-config-growpart.txt b/doc/examples/cloud-config-growpart.txt
index a459573d..393d5164 100644
--- a/doc/examples/cloud-config-growpart.txt
+++ b/doc/examples/cloud-config-growpart.txt
@@ -5,12 +5,10 @@
 #
 #  mode:
 #    values:
-#     * auto: use any option possible (growpart or parted)
+#     * auto: use any option possible (any available)
 #             if none are available, do not warn, but debug.
 #     * growpart: use growpart to grow partitions
 #             if growpart is not available, this is an error.
-#     * parted: use parted (parted resizepart) to resize partitions
-#             if parted is not available, this is an error.
 #     * off, false
 #
 # devices:
diff --git a/doc/examples/cloud-config-landscape.txt b/doc/examples/cloud-config-landscape.txt
index e4d23cc9..74e07b62 100644
--- a/doc/examples/cloud-config-landscape.txt
+++ b/doc/examples/cloud-config-landscape.txt
@@ -6,6 +6,9 @@
 # 
 # Note: 'tags' should be specified as a comma delimited string
 # rather than a list.
+#
+# You can get example key/values by running 'landscape-config',
+# answer question, then look at /etc/landscape/client.config
 landscape:
   client:
     url: "https://landscape.canonical.com/message-system"
@@ -13,3 +16,7 @@ landscape:
     data_path: "/var/lib/landscape/client"
     http_proxy: "http://my.proxy.com/foobar"
     tags: "server,cloud"
+    computer_title = footitle
+    https_proxy = fooproxy
+    registration_key = fookey
+    account_name = fooaccount
diff --git a/doc/examples/cloud-config-vendor-data.txt b/doc/examples/cloud-config-vendor-data.txt
new file mode 100644
index 00000000..7f90847b
--- /dev/null
+++ b/doc/examples/cloud-config-vendor-data.txt
@@ -0,0 +1,16 @@
+#cloud-config
+#
+# This explains how to control vendordata via a cloud-config
+#
+# On select Datasources, vendors have a channel for the consumptions
+# of all support user-data types via a special channel called
+# vendordata. Users of the end system are given ultimate control.
+#
+vendor_data:
+    enabled: True
+    prefix: /usr/bin/ltrace
+
+# enabled: whether it is enabled or not
+# prefix: the command to run before any vendor scripts.
+#   Note: this is a fairly weak method of containment. It should
+#         be used to profile a script, not to prevent its run
diff --git a/doc/rtd/conf.py b/doc/rtd/conf.py
index c9ae79f4..52a8f92b 100644
--- a/doc/rtd/conf.py
+++ b/doc/rtd/conf.py
@@ -1,4 +1,5 @@
-import sys, os
+import os
+import sys
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
diff --git a/doc/rtd/topics/datasources.rst b/doc/rtd/topics/datasources.rst
index 5543ed34..cc0d0ede 100644
--- a/doc/rtd/topics/datasources.rst
+++ b/doc/rtd/topics/datasources.rst
@@ -130,10 +130,6 @@ To see which versions are supported from your cloud provider use the following U
     ...
     latest
         
-**Note:** internally in cloudinit the `boto`_ library used to fetch the instance
-userdata and instance metadata, feel free to check that library out, it provides
-many other useful EC2 functionality.
-
 ---------------------------
 Config Drive
 ---------------------------
diff --git a/doc/sources/smartos/README.rst b/doc/sources/smartos/README.rst
index 8b63e520..e63f311f 100644
--- a/doc/sources/smartos/README.rst
+++ b/doc/sources/smartos/README.rst
@@ -16,11 +16,35 @@ responds with the status and if "SUCCESS" returns until a single ".\n".
 
 New versions of the SmartOS tooling will include support for base64 encoded data.
 
-Userdata
---------
-
-In SmartOS parlance, user-data is a actually meta-data. This userdata can be
-provided as key-value pairs.
+Meta-data channels
+------------------
+
+Cloud-init supports three modes of delivering user/meta-data via the flexible
+channels of SmartOS.
+
+* user-data is written to /var/db/user-data
+  - per the spec, user-data is for consumption by the end-user, not provisioning
+    tools
+  - cloud-init entirely ignores this channel other than writting it to disk
+  - removal of the meta-data key means that /var/db/user-data gets removed
+  - a backup of previous meta-data is maintained as /var/db/user-data.<timestamp>
+    - <timestamp> is the epoch time when cloud-init ran
+
+* user-script is written to /var/lib/cloud/scripts/per-boot/99_user_data
+  - this is executed each boot
+  - a link is created to /var/db/user-script
+  - previous versions of the user-script is written to
+    /var/lib/cloud/scripts/per-boot.backup/99_user_script.<timestamp>.
+    - <timestamp> is the epoch time when cloud-init ran.
+  - when the 'user-script' meta-data key goes missing, the user-script is
+    removed from the file system, although a backup is maintained.
+  - if the script is not shebanged (i.e. starts with #!<executable>), then
+    or is not an executable, cloud-init will add a shebang of "#!/bin/bash"
+
+* cloud-init:user-data is treated like on other Clouds.
+  - this channel is used for delivering _all_ cloud-init instructions
+  - scripts delivered over this channel must be well formed (i.e. must have
+    a shebang)
 
 Cloud-init supports reading the traditional meta-data fields supported by the
 SmartOS tools. These are:
@@ -32,19 +56,49 @@ SmartOS tools. These are:
 Note: At this time iptables_disable and enable_motd_sys_info are read but
     are not actioned.
 
-user-script
------------
-
-SmartOS traditionally supports sending over a user-script for execution at the
-rc.local level. Cloud-init supports running user-scripts as if they were
-cloud-init user-data. In this sense, anything with a shell interpreter
-directive will run.
-
-user-data and user-script
--------------------------
-
-In the event that a user defines the meta-data key of "user-data" it will
-always supersede any user-script data. This is for consistency.
+disabling user-script
+---------------------
+
+Cloud-init uses the per-boot script functionality to handle the execution
+of the user-script.  If you want to prevent this use a cloud-config of:
+
+#cloud-config
+cloud_final_modules:
+ - scripts-per-once
+ - scripts-per-instance
+ - scripts-user
+ - ssh-authkey-fingerprints
+ - keys-to-console
+ - phone-home
+ - final-message
+ - power-state-change
+
+Alternatively you can use the json patch method
+#cloud-config-jsonp
+[
+     { "op": "replace",
+       "path": "/cloud_final_modules",
+       "value": ["scripts-per-once",
+                 "scripts-per-instance",
+                 "scripts-user",
+                 "ssh-authkey-fingerprints",
+                 "keys-to-console",
+                 "phone-home",
+                 "final-message",
+                 "power-state-change"]
+     }
+]
+
+The default cloud-config includes "script-per-boot". Cloud-init will still
+ingest and write the user-data but will not execute it, when you disable
+the per-boot script handling.
+
+Note: Unless you have an explicit use-case, it is recommended that you not
+        disable the per-boot script execution, especially if you are using
+        any of the life-cycle management features of SmartOS.
+
+The cloud-config needs to be delivered over the cloud-init:user-data channel
+in order for cloud-init to ingest it.
 
 base64
 ------
@@ -54,6 +108,8 @@ are provided by SmartOS:
  * root_authorized_keys
  * enable_motd_sys_info
  * iptables_disable
+ * user-data
+ * user-script
 
 This list can be changed through system config of variable 'no_base64_decode'.
 
diff --git a/doc/vendordata.txt b/doc/vendordata.txt
new file mode 100644
index 00000000..9acbe41c
--- /dev/null
+++ b/doc/vendordata.txt
@@ -0,0 +1,53 @@
+=== Overview ===
+Vendordata is data provided by the entity that launches an instance
+(for example, the cloud provider).  This data can be used to
+customize the image to fit into the particular environment it is
+being run in.
+
+Vendordata follows the same rules as user-data, with the following
+caveats:
+    1. Users have ultimate control over vendordata. They can disable its
+       execution or disable handling of specific parts of multipart input.
+    2. By default it only runs on first boot
+    3. Vendordata can be disabled by the user. If the use of vendordata is
+       required for the instance to run, then vendordata should not be
+       used.
+    4. user supplied cloud-config is merged over cloud-config from
+       vendordata.
+
+Users providing cloud-config data can use the '#cloud-config-jsonp' method
+to more finely control their modifications to the vendor supplied
+cloud-config.  For example, if both vendor and user have provided
+'runcnmd' then the default merge handler will cause the user's runcmd to
+override the one provided by the vendor.  To append to 'runcmd', the user
+could better provide multipart input with a cloud-config-jsonp part like:
+ #cloud-config-jsonp
+ [{ "op": "add", "path": "/runcmd", "value": ["my", "command", "here"]}]
+ 
+Further, we strongly advise vendors to not 'be evil'. By evil, we
+mean any action that could compromise a system. Since users trust
+you, please take care to make sure that any vendordata is safe,
+atomic, idempotent and does not put your users at risk.
+
+=== Input Formats ===
+cloud-init will download and cache to filesystem any vendor-data that it
+finds.  Vendordata is handled exactly like user-data.  That means that
+the vendor can supply multipart input and have those parts acted on
+in the same way as user-data.
+
+The only differences are:
+ * user-scripts are stored in a different location than user-scripts (to
+   avoid namespace collision)
+ * user can disable part handlers by cloud-config settings.
+   For example, to disable handling of 'part-handlers' in vendor-data,
+   the user could provide user-data like this:
+    #cloud-config
+    vendordata: {excluded: 'text/part-handler'}
+
+=== Examples ===
+There are examples in the examples subdirectory.
+Additionally, the 'tools' directory contains 'write-mime-multipart',
+which can be used to easily generate mime-multi-part files from a list
+of input files.  That data can then be given to an instance.
+
+See 'write-mime-multipart --help' for usage.