Current File : //usr/share/doc/cloud-init/userdata.txt
=== 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 another.
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.
* 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.
Mini Shell