From 127f0f5076bf8e5c53dd538899199455ebc08fbc Mon Sep 17 00:00:00 2001 From: Scott Moser Date: Thu, 10 Nov 2016 16:42:43 -0500 Subject: doc: make the RST files consistently formated and other improvements. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The biggest things here are: * move doc/sources/*/README.rst to doc/rtd/topics/datasources This gives each datasource a page in the rtd docs, which make it easier to read. * consistently use the same header style throughout. As suggested at http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html use: # with overline, for parts * with overline, for chapters =, for sections -, for subsections ^, for subsubsections “, for paragraphs Also, move and re-format vendor-data documentation to rtd. --- doc/sources/smartos/README.rst | 149 ----------------------------------------- 1 file changed, 149 deletions(-) delete mode 100644 doc/sources/smartos/README.rst (limited to 'doc/sources/smartos') diff --git a/doc/sources/smartos/README.rst b/doc/sources/smartos/README.rst deleted file mode 100644 index e63f311f..00000000 --- a/doc/sources/smartos/README.rst +++ /dev/null @@ -1,149 +0,0 @@ -================== -SmartOS Datasource -================== - -This datasource finds metadata and user-data from the SmartOS virtualization -platform (i.e. Joyent). - -Please see http://smartos.org/ for information about SmartOS. - -SmartOS Platform ----------------- -The SmartOS virtualization platform uses 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: something queries for the data, the console responds -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. - -Meta-data channels ------------------- - -Cloud-init supports three modes of delivering user/meta-data via the flexible -channels of SmartOS. - -* user-data is written to /var/db/user-data - - per the spec, user-data is for consumption by the end-user, not provisioning - tools - - cloud-init entirely ignores this channel other than writting it to disk - - removal of the meta-data key means that /var/db/user-data gets removed - - a backup of previous meta-data is maintained as /var/db/user-data. - - is the epoch time when cloud-init ran - -* user-script is written to /var/lib/cloud/scripts/per-boot/99_user_data - - this is executed each boot - - a link is created to /var/db/user-script - - previous versions of the user-script is written to - /var/lib/cloud/scripts/per-boot.backup/99_user_script.. - - is the epoch time when cloud-init ran. - - when the 'user-script' meta-data key goes missing, the user-script is - removed from the file system, although a backup is maintained. - - if the script is not shebanged (i.e. starts with #!), then - or is not an executable, cloud-init will add a shebang of "#!/bin/bash" - -* cloud-init:user-data is treated like on other Clouds. - - this channel is used for delivering _all_ cloud-init instructions - - scripts delivered over this channel must be well formed (i.e. must have - a shebang) - -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. - -disabling user-script ---------------------- - -Cloud-init uses the per-boot script functionality to handle the execution -of the user-script. If you want to prevent this use a cloud-config of: - -#cloud-config -cloud_final_modules: - - scripts-per-once - - scripts-per-instance - - scripts-user - - ssh-authkey-fingerprints - - keys-to-console - - phone-home - - final-message - - power-state-change - -Alternatively you can use the json patch method -#cloud-config-jsonp -[ - { "op": "replace", - "path": "/cloud_final_modules", - "value": ["scripts-per-once", - "scripts-per-instance", - "scripts-user", - "ssh-authkey-fingerprints", - "keys-to-console", - "phone-home", - "final-message", - "power-state-change"] - } -] - -The default cloud-config includes "script-per-boot". Cloud-init will still -ingest and write the user-data but will not execute it, when you disable -the per-boot script handling. - -Note: Unless you have an explicit use-case, it is recommended that you not - disable the per-boot script execution, especially if you are using - any of the life-cycle management features of SmartOS. - -The cloud-config needs to be delivered over the cloud-init:user-data channel -in order for cloud-init to ingest it. - -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 - * user-data - * user-script - -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-: - for any key, if there exists an entry in the metadata for 'b64-' - Then 'b64-' 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. - -disk_aliases and ephemeral disk: ---------------- -By default, SmartOS only supports a single ephemeral disk. That disk is -completely empty (un-partitioned with no filesystem). - -The SmartOS datasource has built-in cloud-config which instructs the -'disk_setup' module to partition and format the ephemeral disk. - -You can control the disk_setup then in 2 ways: - 1. through the datasource config, you can change the 'alias' of - ephermeral0 to reference another device. The default is: - 'disk_aliases': {'ephemeral0': '/dev/vdb'}, - Which means anywhere disk_setup sees a device named 'ephemeral0' - then /dev/vdb will be substituted. - 2. you can provide disk_setup or fs_setup data in user-data to overwrite - the datasource's built-in values. - -See doc/examples/cloud-config-disk-setup.txt for information on disk_setup. -- cgit v1.2.3