=== 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 cloud-init can read this input and act on it in different ways. === Input Formats === cloud-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 * Include File Once begins with #include-once or Content-Type: text/x-include-once-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 This file will just be downloaded only once per instance, and its contents cached for subsequent boots. This allows you to pass in one-time-use or expiring URLs. * 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. * Cloud Boothook begins with #cloud-boothook or Content-Type: text/cloud-boothook This content is "boothook" data. It is stored in a file under /var/lib/cloud and then executed immediately. This is the earliest "hook" available. Note, that there is no mechanism provided for running only once. The boothook must take care of this itself. It is provided with the instance id in the environment variable "INSTANCE_ID". This could be made use of to provide a 'once-per-instance' === 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.