summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorScott Moser <smoser@ubuntu.com>2010-01-26 22:53:00 -0500
committerScott Moser <smoser@ubuntu.com>2010-01-26 22:53:00 -0500
commiteb74cd6f36a2f4d2ebdee04d6b388834b1bc72d4 (patch)
tree89d6cdf38758b68639bf5f8d8fbcb220f2ce1f71 /doc
parent4f389802609dd1a764bd93f2babda7e9eef7f1ba (diff)
downloadvyos-cloud-init-eb74cd6f36a2f4d2ebdee04d6b388834b1bc72d4.tar.gz
vyos-cloud-init-eb74cd6f36a2f4d2ebdee04d6b388834b1bc72d4.zip
add doc/userdata.txt, move examples to doc/.
Diffstat (limited to 'doc')
-rw-r--r--doc/examples/cloud-config-TODO.txt35
-rw-r--r--doc/examples/cloud-config.txt130
-rw-r--r--doc/examples/include.txt5
-rw-r--r--doc/examples/plain-ignored.txt2
-rw-r--r--doc/examples/upstart-cloud-config.txt12
-rw-r--r--doc/examples/upstart-rclocal.txt12
-rw-r--r--doc/examples/user-script.txt8
-rw-r--r--doc/userdata.txt57
8 files changed, 261 insertions, 0 deletions
diff --git a/doc/examples/cloud-config-TODO.txt b/doc/examples/cloud-config-TODO.txt
new file mode 100644
index 00000000..20db618f
--- /dev/null
+++ b/doc/examples/cloud-config-TODO.txt
@@ -0,0 +1,35 @@
+# Add apt configuration files
+# Add an apt.conf.d/ file with the relevant content
+#
+# See apt.conf man page for more information.
+#
+# Defaults:
+# + filename: 00-boot-conf
+#
+apt_conf:
+
+ # Creates an apt proxy configuration in /etc/apt/apt.conf.d/01-proxy
+ - filename: "01-proxy"
+ content: |
+ Acquire::http::Proxy "http://proxy.example.org:3142/ubuntu";
+
+ # Add the following line to /etc/apt/apt.conf.d/00-boot-conf
+ # (run debconf at a critical priority)
+ - content: |
+ DPkg::Pre-Install-Pkgs:: "/usr/sbin/dpkg-preconfigure --apt -p critical|| true";
+
+# Provide debconf answers
+#
+# See debconf-set-selections man page.
+#
+# Default: none
+#
+debconf_selections: | # Need to perserve newlines
+ # Force debconf priority to critical.
+ debconf debconf/priority select critical
+
+ # Override default frontend to readline, but allow user to select.
+ debconf debconf/frontend select readline
+ debconf debconf/frontend seen false
+
+
diff --git a/doc/examples/cloud-config.txt b/doc/examples/cloud-config.txt
new file mode 100644
index 00000000..b808f99a
--- /dev/null
+++ b/doc/examples/cloud-config.txt
@@ -0,0 +1,130 @@
+#cloud-config
+# Update apt database on first boot
+# (ie run apt-get update)
+#
+# Default: true
+#
+apt_update: false
+
+# Upgrade the instance on first boot
+# (ie run apt-get upgrade)
+#
+# Default: false
+#
+apt_upgrade: true
+
+# Add apt repositories
+#
+# Default: auto select based on cloud metadata
+# in ec2, the default is <region>.archive.ubuntu.com
+apt_mirror: http://us.archive.ubuntu.com/ubuntu/
+
+# Preserve existing /etc/apt/sources.list
+# Default: overwrite sources_list with mirror. If this is true
+# then apt_mirror above will have no effect
+apt_preserve_sources_list: true
+
+apt_sources:
+
+ # PPA shortcut:
+ # * Setup correct apt sources.list line
+ # * Import the signing key from LP
+ #
+ # See https://help.launchpad.net/Packaging/PPA for more information
+ # this requires 'add-apt-repository'
+ - source: "ppa:smoser/ppa" # Quote the string
+
+ # Custom apt repository:
+ # * all that is required is 'source'
+ # * Creates a file in /etc/apt/sources.list.d/ for the sources list entry
+ # * [optional] Import the apt signing key from the keyserver
+ # * Defaults:
+ # + keyserver: keyserver.ubuntu.com
+ # + filename: cloud_config_sources.list
+ #
+ # See sources.list man page for more information about the format
+ - source: deb http://archive.ubuntu.com/ubuntu karmic-backports main universe multiverse restricted
+
+ # this would have the same end effect as 'ppa:byobu/ppa'
+ - source: "deb http://ppa.launchpad.net/byobu/ppa/ubuntu karmic main"
+ keyid: F430BBA5 # GPG key ID published on a key server
+ filename: byobu-ppa.list
+
+ # Custom apt repository:
+ # * The apt signing key can also be specified
+ # by providing a pgp public key block
+ # * Providing the PBG key here is the most robust method for
+ # specifying a key, as it removes dependency on a remote key server
+
+ - source: deb http://ppa.launchpad.net/alestic/ppa/ubuntu karmic main
+ key: | # The value needs to start with -----BEGIN PGP PUBLIC KEY BLOCK-----
+ -----BEGIN PGP PUBLIC KEY BLOCK-----
+ Version: SKS 1.0.10
+
+ mI0ESpA3UQEEALdZKVIMq0j6qWAXAyxSlF63SvPVIgxHPb9Nk0DZUixn+akqytxG4zKCONz6
+ qLjoBBfHnynyVLfT4ihg9an1PqxRnTO+JKQxl8NgKGz6Pon569GtAOdWNKw15XKinJTDLjnj
+ 9y96ljJqRcpV9t/WsIcdJPcKFR5voHTEoABE2aEXABEBAAG0GUxhdW5jaHBhZCBQUEEgZm9y
+ IEFsZXN0aWOItgQTAQIAIAUCSpA3UQIbAwYLCQgHAwIEFQIIAwQWAgMBAh4BAheAAAoJEA7H
+ 5Qi+CcVxWZ8D/1MyYvfj3FJPZUm2Yo1zZsQ657vHI9+pPouqflWOayRR9jbiyUFIn0VdQBrP
+ t0FwvnOFArUovUWoKAEdqR8hPy3M3APUZjl5K4cMZR/xaMQeQRZ5CHpS4DBKURKAHC0ltS5o
+ uBJKQOZm5iltJp15cgyIkBkGe8Mx18VFyVglAZey
+ =Y2oI
+ -----END PGP PUBLIC KEY BLOCK-----
+
+# Install additional packages on first boot
+#
+# Default: none
+#
+# if packages are specified, this apt_update will be set to true
+#
+packages:
+ - pwgen
+ - pastebinit
+
+
+# add each entry to ~/.ssh/authorized_keys for the configured user
+ssh_authorized_keys:
+ - ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAGEA3FSyQwBI6Z+nCSjUUk8EEAnnkhXlukKoUPND/RRClWz2s5TCzIkd3Ou5+Cyz71X0XmazM3l5WgeErvtIwQMyT1KjNoMhoJMrJnWqQPOt5Q8zWd9qG7PBl9+eiH5qV7NZ mykey@host
+ - ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEA3I7VUf2l5gSn5uavROsc5HRDpZdQueUq5ozemNSj8T7enqKHOEaFoU2VoPgGEWC9RyzSQVeyD6s7APMcE82EtmW4skVEgEGSbDc1pvxzxtchBj78hJP6Cf5TCMFSXw+Fz5rF1dR23QDbN1mkHs7adr8GW4kSWqU7Q7NDwfIrJJtO7Hi42GyXtvEONHbiRPOe8stqUly7MvUoN+5kfjBM8Qqpfl2+FNhTYWpMfYdPUnE7u536WqzFmsaqJctz3gBxH9Ex7dFtrxR4qiqEr9Qtlu3xGn7Bw07/+i1D+ey3ONkZLN+LQ714cgj8fRS4Hj29SCmXp5Kt5/82cD/VN3NtHw== smoser@brickies
+
+# Send pre-generated ssh private keys to the server
+# If these are present, they will be written to /etc/ssh and
+# new random keys will not be generated
+ssh_keys:
+ rsa_private: |
+ -----BEGIN RSA PRIVATE KEY-----
+ MIIBxwIBAAJhAKD0YSHy73nUgysO13XsJmd4fHiFyQ+00R7VVu2iV9Qcon2LZS/x
+ 1cydPZ4pQpfjEha6WxZ6o8ci/Ea/w0n+0HGPwaxlEG2Z9inNtj3pgFrYcRztfECb
+ 1j6HCibZbAzYtwIBIwJgO8h72WjcmvcpZ8OvHSvTwAguO2TkR6mPgHsgSaKy6GJo
+ PUJnaZRWuba/HX0KGyhz19nPzLpzG5f0fYahlMJAyc13FV7K6kMBPXTRR6FxgHEg
+ L0MPC7cdqAwOVNcPY6A7AjEA1bNaIjOzFN2sfZX0j7OMhQuc4zP7r80zaGc5oy6W
+ p58hRAncFKEvnEq2CeL3vtuZAjEAwNBHpbNsBYTRPCHM7rZuG/iBtwp8Rxhc9I5w
+ ixvzMgi+HpGLWzUIBS+P/XhekIjPAjA285rVmEP+DR255Ls65QbgYhJmTzIXQ2T9
+ luLvcmFBC6l35Uc4gTgg4ALsmXLn71MCMGMpSWspEvuGInayTCL+vEjmNBT+FAdO
+ W7D4zCpI43jRS9U06JVOeSc9CDk2lwiA3wIwCTB/6uc8Cq85D9YqpM10FuHjKpnP
+ REPPOyrAspdeOAV+6VKRavstea7+2DZmSUgE
+ -----END RSA PRIVATE KEY-----
+
+ rsa_public: ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAGEAoPRhIfLvedSDKw7XdewmZ3h8eIXJD7TRHtVW7aJX1ByifYtlL/HVzJ09nilCl+MSFrpbFnqjxyL8Rr/DSf7QcY/BrGUQbZn2Kc22PemAWthxHO18QJvWPocKJtlsDNi3 smoser@localhost
+
+ dsa_private: |
+ -----BEGIN DSA PRIVATE KEY-----
+ MIIBuwIBAAKBgQDP2HLu7pTExL89USyM0264RCyWX/CMLmukxX0Jdbm29ax8FBJT
+ pLrO8TIXVY5rPAJm1dTHnpuyJhOvU9G7M8tPUABtzSJh4GVSHlwaCfycwcpLv9TX
+ DgWIpSj+6EiHCyaRlB1/CBp9RiaB+10QcFbm+lapuET+/Au6vSDp9IRtlQIVAIMR
+ 8KucvUYbOEI+yv+5LW9u3z/BAoGBAI0q6JP+JvJmwZFaeCMMVxXUbqiSko/P1lsa
+ LNNBHZ5/8MOUIm8rB2FC6ziidfueJpqTMqeQmSAlEBCwnwreUnGfRrKoJpyPNENY
+ d15MG6N5J+z81sEcHFeprryZ+D3Ge9VjPq3Tf3NhKKwCDQ0240aPezbnjPeFm4mH
+ bYxxcZ9GAoGAXmLIFSQgiAPu459rCKxT46tHJtM0QfnNiEnQLbFluefZ/yiI4DI3
+ 8UzTCOXLhUA7ybmZha+D/csj15Y9/BNFuO7unzVhikCQV9DTeXX46pG4s1o23JKC
+ /QaYWNMZ7kTRv+wWow9MhGiVdML4ZN4XnifuO5krqAybngIy66PMEoQCFEIsKKWv
+ 99iziAH0KBMVbxy03Trz
+ -----END DSA PRIVATE KEY-----
+
+ dsa_public: ssh-dss AAAAB3NzaC1kc3MAAACBAM/Ycu7ulMTEvz1RLIzTbrhELJZf8Iwua6TFfQl1ubb1rHwUElOkus7xMhdVjms8AmbV1Meem7ImE69T0bszy09QAG3NImHgZVIeXBoJ/JzByku/1NcOBYilKP7oSIcLJpGUHX8IGn1GJoH7XRBwVub6Vqm4RP78C7q9IOn0hG2VAAAAFQCDEfCrnL1GGzhCPsr/uS1vbt8/wQAAAIEAjSrok/4m8mbBkVp4IwxXFdRuqJKSj8/WWxos00Ednn/ww5QibysHYULrOKJ1+54mmpMyp5CZICUQELCfCt5ScZ9GsqgmnI80Q1h3Xkwbo3kn7PzWwRwcV6muvJn4PcZ71WM+rdN/c2EorAINDTbjRo97NueM94WbiYdtjHFxn0YAAACAXmLIFSQgiAPu459rCKxT46tHJtM0QfnNiEnQLbFluefZ/yiI4DI38UzTCOXLhUA7ybmZha+D/csj15Y9/BNFuO7unzVhikCQV9DTeXX46pG4s1o23JKC/QaYWNMZ7kTRv+wWow9MhGiVdML4ZN4XnifuO5krqAybngIy66PMEoQ= smoser@localhost
+
+
+# remove access to the ec2 metadata service early in boot via null route
+# default: false (service available)
+disable_ec2_metadata: true
+
diff --git a/doc/examples/include.txt b/doc/examples/include.txt
new file mode 100644
index 00000000..5bdc7991
--- /dev/null
+++ b/doc/examples/include.txt
@@ -0,0 +1,5 @@
+#include
+# entries are one url per line. comment lines beginning with '#' are allowed
+# urls are passed to urllib.urlopen, so the format must be supported there
+http://www.ubuntu.com/robots.txt
+http://www.w3schools.com/html/lastpage.htm
diff --git a/doc/examples/plain-ignored.txt b/doc/examples/plain-ignored.txt
new file mode 100644
index 00000000..fb2b59dc
--- /dev/null
+++ b/doc/examples/plain-ignored.txt
@@ -0,0 +1,2 @@
+#ignored
+Nothing will be done with this part by the UserDataHandler
diff --git a/doc/examples/upstart-cloud-config.txt b/doc/examples/upstart-cloud-config.txt
new file mode 100644
index 00000000..1fcec34d
--- /dev/null
+++ b/doc/examples/upstart-cloud-config.txt
@@ -0,0 +1,12 @@
+#upstart-job
+description "My test job"
+
+start on cloud-config
+console output
+task
+
+script
+echo "====BEGIN======="
+echo "HELLO WORLD: $UPSTART_JOB"
+echo "=====END========"
+end script
diff --git a/doc/examples/upstart-rclocal.txt b/doc/examples/upstart-rclocal.txt
new file mode 100644
index 00000000..5cd049a9
--- /dev/null
+++ b/doc/examples/upstart-rclocal.txt
@@ -0,0 +1,12 @@
+#upstart-job
+description "a test upstart job"
+
+start on stopped rc RUNLEVEL=[2345]
+console output
+task
+
+script
+echo "====BEGIN======="
+echo "HELLO RC.LOCAL LIKE WORLD: $UPSTART_JOB"
+echo "=====END========"
+end script
diff --git a/doc/examples/user-script.txt b/doc/examples/user-script.txt
new file mode 100644
index 00000000..6a87cad5
--- /dev/null
+++ b/doc/examples/user-script.txt
@@ -0,0 +1,8 @@
+#!/bin/sh
+
+cat <<EOF
+============================
+My name is ${0}
+I was input via user data
+============================
+EOF
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.