← Back to branch summary

~smoser/cloud-init/lp-1077700

« back to all changes in this revision

Viewing changes to doc/userdata.txt

  • Committer: Scott Moser
  • Date: 2010-01-27 03:53:00 UTC
  • Revision ID: smoser@ubuntu.com-20100127035300-e63jd2p9ewmc78w8
add doc/userdata.txt, move examples to doc/.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/userdata.txt
 
1
=== Overview ===
 
2
Userdata is data provided by the entity that launches an instance.
 
3
The cloud provider makes this data available to the instance via in one
 
4
way or anohter.  
 
5
 
 
6
In EC2, the data is provided by the user via the '--user-data' or
 
7
'user-data-file' argument to ec2-run-instances.  The EC2 cloud makes the
 
8
data available to the instance via its meta-data service at 
 
9
http://169.254.169.254/latest/user-data
 
10
 
 
11
ec2-init can read this input and act on it in different ways.
 
12
 
 
13
=== Input Formats ===
 
14
ec2-init will download and cache to filesystem any user-data that it
 
15
finds.  However, certain types of user-data are handled specially.
 
16
 
 
17
 * Gzip Compressed Content
 
18
   content found to be gzip compressed will be uncompressed, and 
 
19
   these rules applied to the uncompressed data
 
20
 
 
21
 * Mime Multi Part archive
 
22
   This list of rules is applied to each part of this multi-part file
 
23
   Using a mime-multi part file, the user can specify more than one
 
24
   type of data.  For example, both a user data script and a
 
25
   cloud-config type could be specified.
 
26
 
 
27
 * User-Data Script
 
28
   begins with: #!            or Content-Type: text/x-shellscript
 
29
   script will be executed at "rc.local-like" level during first boot.
 
30
   rc.local-like means "very late in the boot sequence"
 
31
 
 
32
 * Include File
 
33
   begins with  #include      or Content-Type: text/x-include-url
 
34
   This content is a "include" file.  The file contains a list of
 
35
   urls, one per line.  Each of the URLs will be read, and their content
 
36
   will be passed through this same set of rules.  Ie, the content
 
37
   read from the URL can be gzipped, mime-multi-part, or plain text
 
38
 
 
39
 * Cloud Config Data
 
40
   begins with  #cloud-config or Content-Type: text/cloud-config
 
41
 
 
42
   This content is "cloud-config" data.  See the examples for a
 
43
   commented example of supported config formats.
 
44
 
 
45
 * Upstart Job
 
46
   begins with  #upstart-job  or Content-Type: text/upstart-job
 
47
   
 
48
   Content is placed into a file in /etc/init, and will be consumed
 
49
   by upstart as any other upstart job.
 
50
 
 
51
=== Examples ===
 
52
There are examples in the examples subdirectory.
 
53
Additionally, the 'tools' directory contains 'write-mime-multipart',
 
54
which can be used to easily generate mime-multi-part files from a list
 
55
of input files.  That data can then be given to an instance.
 
56
 
 
57
See 'write-mime-multipart --help' for usage.