summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorScott Moser <smoser@ubuntu.com>2013-08-24 00:12:24 -0400
committerScott Moser <smoser@ubuntu.com>2013-08-24 00:12:24 -0400
commit1d27cd75eaaeef7b72f3be77de24da815c82a825 (patch)
tree177feb675ec25234ba8361518a2c8dd81736a961 /doc
parent7af11ba50c8311ceb545b830716c78929079a0cd (diff)
parent10c8ec1e5c1b16572a38afd08ee794d28c450054 (diff)
downloadvyos-cloud-init-1d27cd75eaaeef7b72f3be77de24da815c82a825.tar.gz
vyos-cloud-init-1d27cd75eaaeef7b72f3be77de24da815c82a825.zip
support base64 encoded data in the smart os datasource.
The big benefit of this is that now the user can put in arbitrary data into the user-data or user-script keys and there is no concern about the data being incorrectly read. Previously, if data contained '\n.\n', there was no way to differenciate that from a end of message in the serial communication format. It would be recommended that anyone using user-data on smartos base64 encode that data and specify a key of 'b64-user-data' with value 'true'.
Diffstat (limited to 'doc')
-rw-r--r--doc/examples/cloud-config-datasources.txt12
-rw-r--r--doc/sources/smartos/README.rst72
2 files changed, 82 insertions, 2 deletions
diff --git a/doc/examples/cloud-config-datasources.txt b/doc/examples/cloud-config-datasources.txt
index 6544448e..65a3cdf5 100644
--- a/doc/examples/cloud-config-datasources.txt
+++ b/doc/examples/cloud-config-datasources.txt
@@ -55,5 +55,13 @@ datasource:
# Smart OS datasource works over a serial console interacting with
# a server on the other end. By default, the second serial console is the
# device. SmartOS also uses a serial timeout of 60 seconds.
- serial device: /dev/ttyS1
- serial timeout: 60
+ serial_device: /dev/ttyS1
+ serial_timeout: 60
+
+ # a list of keys that will not be base64 decoded even if base64_all
+ no_base64_decode: ['root_authorized_keys', 'motd_sys_info',
+ 'iptables_disable']
+ # a plaintext, comma delimited list of keys whose values are b64 encoded
+ base64_keys: []
+ # a boolean indicating that all keys not in 'no_base64_decode' are encoded
+ base64_all: False
diff --git a/doc/sources/smartos/README.rst b/doc/sources/smartos/README.rst
new file mode 100644
index 00000000..fd4e496d
--- /dev/null
+++ b/doc/sources/smartos/README.rst
@@ -0,0 +1,72 @@
+==================
+SmartOS Datasource
+==================
+
+This datasource finds metadata and user-data from the SmartOS virtualization
+platform (i.e. Joyent).
+
+SmartOS Platform
+----------------
+The SmartOS virtualization platform meta-data to the instance via the second
+serial console. On Linux, this is /dev/ttyS1. The data is a provided via a
+simple protocol, where something queries for the userdata, where the console
+responds with the status and if "SUCCESS" returns until a single ".\n".
+
+New versions of the SmartOS tooling will include support for base64 encoded data.
+
+Userdata
+--------
+
+In SmartOS parlance, user-data is a actually meta-data. This userdata can be
+provided a key-value pairs.
+
+Cloud-init supports reading the traditional meta-data fields supported by the
+SmartOS tools. These are:
+ * root_authorized_keys
+ * hostname
+ * enable_motd_sys_info
+ * iptables_disable
+
+Note: At this time iptables_disable and enable_motd_sys_info are read but
+ are not actioned.
+
+user-script
+-----------
+
+SmartOS traditionally supports sending over a user-script for execution at the
+rc.local level. Cloud-init supports running user-scripts as if they were
+cloud-init user-data. In this sense, anything with a shell interpreter
+directive will run
+
+user-data and user-script
+-------------------------
+
+In the event that a user defines the meta-data key of "user-data" it will
+always supercede any user-script data. This is for consistency.
+
+base64
+------
+
+The following are exempt from base64 encoding, owing to the fact that they
+are provided by SmartOS:
+ * root_authorized_keys
+ * enable_motd_sys_info
+ * iptables_disable
+
+This list can be changed through system config of variable 'no_base64_decode'.
+
+This means that user-script and user-data as well as other values can be
+base64 encoded. Since Cloud-init can only guess as to whether or not something
+is truly base64 encoded, the following meta-data keys are hints as to whether
+or not to base64 decode something:
+ * base64_all: Except for excluded keys, attempt to base64 decode
+ the values. If the value fails to decode properly, it will be
+ returned in its text
+ * base64_keys: A comma deliminated list of which keys are base64 encoded.
+ * b64-<key>:
+ for any key, if there exists an entry in the metadata for 'b64-<key>'
+ Then 'b64-<key>' is expected to be a plaintext boolean indicating whether
+ or not its value is encoded.
+ * no_base64_decode: This is a configuration setting
+ (i.e. /etc/cloud/cloud.cfg.d) that sets which values should not be
+ base64 decoded.