add doc/userdata.txt, move examples to doc/.

9 files changed, 58 insertions, 1 deletions

diff --git a/examples/cloud-config-TODO.txt b/doc/examples/cloud-config-TODO.txt
index 20db618f..20db618f 100644
--- a/examples/cloud-config-TODO.txt
+++ b/doc/examples/cloud-config-TODO.txt
diff --git a/examples/cloud-config.txt b/doc/examples/cloud-config.txt
index b808f99a..b808f99a 100644
--- a/examples/cloud-config.txt
+++ b/doc/examples/cloud-config.txt
diff --git a/examples/include.txt b/doc/examples/include.txt
index 5bdc7991..5bdc7991 100644
--- a/examples/include.txt
+++ b/doc/examples/include.txt
diff --git a/examples/plain-ignored.txt b/doc/examples/plain-ignored.txt
index fb2b59dc..fb2b59dc 100644
--- a/examples/plain-ignored.txt
+++ b/doc/examples/plain-ignored.txt
diff --git a/examples/upstart-cloud-config.txt b/doc/examples/upstart-cloud-config.txt
index 1fcec34d..1fcec34d 100644
--- a/examples/upstart-cloud-config.txt
+++ b/doc/examples/upstart-cloud-config.txt
diff --git a/examples/upstart-rclocal.txt b/doc/examples/upstart-rclocal.txt
index 5cd049a9..5cd049a9 100644
--- a/examples/upstart-rclocal.txt
+++ b/doc/examples/upstart-rclocal.txt
diff --git a/examples/user-script.txt b/doc/examples/user-script.txt
index 6a87cad5..6a87cad5 100644
--- a/examples/user-script.txt
+++ b/doc/examples/user-script.txt
diff --git a/doc/userdata.txt b/doc/userdata.txt
new file mode 100644
index 00000000..7ada0ba5
--- /dev/null
+++ b/doc/userdata.txt
@@ -0,0 +1,57 @@
+=== Overview ===
+Userdata is data provided by the entity that launches an instance.
+The cloud provider makes this data available to the instance via in one
+way or anohter.  
+
+In EC2, the data is provided by the user via the '--user-data' or
+'user-data-file' argument to ec2-run-instances.  The EC2 cloud makes the
+data available to the instance via its meta-data service at 
+http://169.254.169.254/latest/user-data
+
+ec2-init can read this input and act on it in different ways.
+
+=== Input Formats ===
+ec2-init will download and cache to filesystem any user-data that it
+finds.  However, certain types of user-data are handled specially.
+
+ * Gzip Compressed Content
+   content found to be gzip compressed will be uncompressed, and 
+   these rules applied to the uncompressed data
+
+ * Mime Multi Part archive
+   This list of rules is applied to each part of this multi-part file
+   Using a mime-multi part file, the user can specify more than one
+   type of data.  For example, both a user data script and a
+   cloud-config type could be specified.
+
+ * User-Data Script
+   begins with: #!            or Content-Type: text/x-shellscript
+   script will be executed at "rc.local-like" level during first boot.
+   rc.local-like means "very late in the boot sequence"
+
+ * Include File
+   begins with  #include      or Content-Type: text/x-include-url
+   This content is a "include" file.  The file contains a list of
+   urls, one per line.  Each of the URLs will be read, and their content
+   will be passed through this same set of rules.  Ie, the content
+   read from the URL can be gzipped, mime-multi-part, or plain text
+
+ * Cloud Config Data
+   begins with  #cloud-config or Content-Type: text/cloud-config
+
+   This content is "cloud-config" data.  See the examples for a
+   commented example of supported config formats.
+
+ * Upstart Job
+   begins with  #upstart-job  or Content-Type: text/upstart-job
+   
+   Content is placed into a file in /etc/init, and will be consumed
+   by upstart as any other upstart job.
+
+=== 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.
diff --git a/tools/write-mime-multipart b/tools/write-mime-multipart
index a6781876..b83073c1 100755
--- a/tools/write-mime-multipart
+++ b/tools/write-mime-multipart
@@ -96,7 +96,7 @@ def main():
         ofile = file(options.output,"wb")
         
     if options.compress:
-        gfile = gzip.GzipFile(fileobj=ofile)
+        gfile = gzip.GzipFile(fileobj=ofile, filename = options.output )
         gfile.write(outer.as_string())
         gfile.close()
     else: