doc: make the RST files consistently formated and other improvements.

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.

14 files changed, 987 insertions, 0 deletions

diff --git a/doc/rtd/topics/datasources/altcloud.rst b/doc/rtd/topics/datasources/altcloud.rst
new file mode 100644
index 00000000..8646e77e
--- /dev/null
+++ b/doc/rtd/topics/datasources/altcloud.rst
@@ -0,0 +1,91 @@
+Alt Cloud
+=========
+
+The datasource altcloud will be used to pick up user data on `RHEVm`_ and `vSphere`_.
+
+RHEVm
+-----
+
+For `RHEVm`_ v3.0 the userdata is injected into the VM using floppy
+injection via the `RHEVm`_ dashboard "Custom Properties". 
+
+The format of the Custom Properties entry must be:
+
+::
+    
+    floppyinject=user-data.txt:<base64 encoded data>
+
+For example to pass a simple bash script:
+
+.. sourcecode:: sh
+    
+    % cat simple_script.bash
+    #!/bin/bash
+    echo "Hello Joe!" >> /tmp/JJV_Joe_out.txt
+
+    % base64 < simple_script.bash
+    IyEvYmluL2Jhc2gKZWNobyAiSGVsbG8gSm9lISIgPj4gL3RtcC9KSlZfSm9lX291dC50eHQK
+
+To pass this example script to cloud-init running in a  `RHEVm`_ v3.0 VM
+set the "Custom Properties" when creating the RHEMv v3.0 VM to:
+
+::
+
+    floppyinject=user-data.txt:IyEvYmluL2Jhc2gKZWNobyAiSGVsbG8gSm9lISIgPj4gL3RtcC9KSlZfSm9lX291dC50eHQK
+
+**NOTE:** The prefix with file name must be: ``floppyinject=user-data.txt:``
+
+It is also possible to launch a `RHEVm`_ v3.0 VM and pass optional user
+data to it using the Delta Cloud. 
+
+For more information on Delta Cloud see: http://deltacloud.apache.org
+
+vSphere
+-------
+
+For VMWare's `vSphere`_ the userdata is injected into the VM as an ISO
+via the cdrom. This can be done using the `vSphere`_ dashboard 
+by connecting an ISO image to the CD/DVD drive.
+
+To pass this example script to cloud-init running in a `vSphere`_ VM
+set the CD/DVD drive when creating the vSphere VM to point to an
+ISO on the data store. 
+
+**Note:** The ISO must contain the user data.
+
+For example, to pass the same ``simple_script.bash`` to vSphere:
+
+Create the ISO
+^^^^^^^^^^^^^^
+
+.. sourcecode:: sh
+    
+    % mkdir my-iso
+
+NOTE: The file name on the ISO must be: ``user-data.txt``
+
+.. sourcecode:: sh
+    
+    % cp simple_scirpt.bash my-iso/user-data.txt
+    % genisoimage -o user-data.iso -r my-iso
+
+Verify the ISO
+^^^^^^^^^^^^^^
+
+.. sourcecode:: sh
+    
+    % sudo mkdir /media/vsphere_iso
+    % sudo mount -o loop JoeV_CI_02.iso /media/vsphere_iso
+    % cat /media/vsphere_iso/user-data.txt
+    % sudo umount /media/vsphere_iso
+
+Then, launch the `vSphere`_ VM the ISO user-data.iso attached as a CDROM.
+
+It is also possible to launch a `vSphere`_ VM and pass optional user
+data to it using the Delta Cloud. 
+
+For more information on Delta Cloud see: http://deltacloud.apache.org
+
+.. _RHEVm: https://www.redhat.com/virtualization/rhev/desktop/rhevm/
+.. _vSphere: https://www.vmware.com/products/datacenter-virtualization/vsphere/overview.html
+.. vi: textwidth=78
diff --git a/doc/rtd/topics/datasources/azure.rst b/doc/rtd/topics/datasources/azure.rst
new file mode 100644
index 00000000..18d7c506
--- /dev/null
+++ b/doc/rtd/topics/datasources/azure.rst
@@ -0,0 +1,155 @@
+Azure
+=====
+
+This datasource finds metadata and user-data from the Azure cloud platform.
+
+Azure Platform
+--------------
+The azure cloud-platform provides initial data to an instance via an attached
+CD formated in UDF.  That CD contains a 'ovf-env.xml' file that provides some
+information.  Additional information is obtained via interaction with the
+"endpoint".
+
+To find the endpoint, we now leverage the dhcp client's ability to log its
+known values on exit.  The endpoint server is special DHCP option 245.
+Depending on your networking stack, this can be done
+by calling a script in /etc/dhcp/dhclient-exit-hooks or a file in
+/etc/NetworkManager/dispatcher.d.  Both of these call a sub-command
+'dhclient_hook' of cloud-init itself. This sub-command will write the client
+information in json format to /run/cloud-init/dhclient.hook/<interface>.json.
+
+In order for cloud-init to leverage this method to find the endpoint, the
+cloud.cfg file must contain:
+
+datasource:
+  Azure:
+    set_hostname: False
+    agent_command: __builtin__
+
+If those files are not available, the fallback is to check the leases file
+for the endpoint server (again option 245).
+
+You can define the path to the lease file with the 'dhclient_lease_file'
+configuration.  The default value is /var/lib/dhcp/dhclient.eth0.leases.
+
+    dhclient_lease_file: /var/lib/dhcp/dhclient.eth0.leases
+
+walinuxagent
+------------
+In order to operate correctly, cloud-init needs walinuxagent to provide much
+of the interaction with azure.  In addition to "provisioning" code, walinux
+does the following on the agent is a long running daemon that handles the
+following things:
+- generate a x509 certificate and send that to the endpoint
+
+waagent.conf config
+^^^^^^^^^^^^^^^^^^^
+in order to use waagent.conf with cloud-init, the following settings are recommended.  Other values can be changed or set to the defaults.
+
+  ::
+
+   # disabling provisioning turns off all 'Provisioning.*' function
+   Provisioning.Enabled=n
+   # this is currently not handled by cloud-init, so let walinuxagent do it.
+   ResourceDisk.Format=y
+   ResourceDisk.MountPoint=/mnt
+
+
+Userdata
+--------
+Userdata is provided to cloud-init inside the ovf-env.xml file. Cloud-init
+expects that user-data will be provided as base64 encoded value inside the
+text child of a element named ``UserData`` or ``CustomData`` which is a direct
+child of the ``LinuxProvisioningConfigurationSet`` (a sibling to ``UserName``)
+If both ``UserData`` and ``CustomData`` are provided behavior is undefined on
+which will be selected.
+
+In the example below, user-data provided is 'this is my userdata', and the
+datasource config provided is ``{"agent_command": ["start", "walinuxagent"]}``.
+That agent command will take affect as if it were specified in system config.
+
+Example:
+
+.. sourcecode:: xml
+
+ <wa:ProvisioningSection>
+  <wa:Version>1.0</wa:Version>
+  <LinuxProvisioningConfigurationSet
+     xmlns="http://schemas.microsoft.com/windowsazure"
+     xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
+   <ConfigurationSetType>LinuxProvisioningConfiguration</ConfigurationSetType>
+   <HostName>myHost</HostName>
+   <UserName>myuser</UserName>
+   <UserPassword/>
+   <CustomData>dGhpcyBpcyBteSB1c2VyZGF0YQ===</CustomData>
+   <dscfg>eyJhZ2VudF9jb21tYW5kIjogWyJzdGFydCIsICJ3YWxpbnV4YWdlbnQiXX0=</dscfg>
+   <DisableSshPasswordAuthentication>true</DisableSshPasswordAuthentication>
+   <SSH>
+    <PublicKeys>
+     <PublicKey>
+      <Fingerprint>6BE7A7C3C8A8F4B123CCA5D0C2F1BE4CA7B63ED7</Fingerprint>
+      <Path>this-value-unused</Path>
+     </PublicKey>
+    </PublicKeys>
+   </SSH>
+   </LinuxProvisioningConfigurationSet>
+ </wa:ProvisioningSection>
+
+Configuration
+-------------
+Configuration for the datasource can be read from the system config's or set
+via the `dscfg` entry in the `LinuxProvisioningConfigurationSet`.  Content in
+dscfg node is expected to be base64 encoded yaml content, and it will be
+merged into the 'datasource: Azure' entry.
+
+The '``hostname_bounce: command``' entry can be either the literal string
+'builtin' or a command to execute.  The command will be invoked after the
+hostname is set, and will have the 'interface' in its environment.  If
+``set_hostname`` is not true, then ``hostname_bounce`` will be ignored.
+
+An example might be:
+  command:  ["sh", "-c", "killall dhclient; dhclient $interface"]
+
+.. code:: yaml
+
+  datasource:
+   agent_command
+   Azure:
+    agent_command: [service, walinuxagent, start]
+    set_hostname: True
+    hostname_bounce:
+     # the name of the interface to bounce
+     interface: eth0
+     # policy can be 'on', 'off' or 'force'
+     policy: on
+     # the method 'bounce' command.
+     command: "builtin"
+     hostname_command: "hostname"
+
+hostname
+--------
+When the user launches an instance, they provide a hostname for that instance.
+The hostname is provided to the instance in the ovf-env.xml file as
+``HostName``.
+
+Whatever value the instance provides in its dhcp request will resolve in the
+domain returned in the 'search' request.
+
+The interesting issue is that a generic image will already have a hostname
+configured.  The ubuntu cloud images have 'ubuntu' as the hostname of the
+system, and the initial dhcp request on eth0 is not guaranteed to occur after
+the datasource code has been run.  So, on first boot, that initial value will
+be sent in the dhcp request and *that* value will resolve.
+
+In order to make the ``HostName`` provided in the ovf-env.xml resolve, a
+dhcp request must be made with the new value.  Walinuxagent (in its current
+version) handles this by polling the state of hostname and bouncing ('``ifdown
+eth0; ifup eth0``' the network interface if it sees that a change has been
+made.
+
+cloud-init handles this by setting the hostname in the DataSource's 'get_data'
+method via '``hostname $HostName``', and then bouncing the interface.  This
+behavior can be configured or disabled in the datasource config.  See
+'Configuration' above.
+
+.. vi: textwidth=78
diff --git a/doc/rtd/topics/datasources/cloudsigma.rst b/doc/rtd/topics/datasources/cloudsigma.rst
new file mode 100644
index 00000000..54963f61
--- /dev/null
+++ b/doc/rtd/topics/datasources/cloudsigma.rst
@@ -0,0 +1,40 @@
+CloudSigma
+==========
+
+This datasource finds metadata and user-data from the `CloudSigma`_ cloud
+platform.  Data transfer occurs through a virtual serial port of the
+`CloudSigma`_'s VM and the presence of network adapter is **NOT** a
+requirement, See `server context`_ in the public documentation for more
+information.
+
+
+Setting a hostname
+------------------
+By default the name of the server will be applied as a hostname on the first
+boot.
+
+
+Providing user-data
+-------------------
+
+You can provide user-data to the VM using the dedicated `meta field`_ in the
+`server context`_ ``cloudinit-user-data``. By default *cloud-config* format is
+expected there and the ``#cloud-config`` header could be omitted. However
+since this is a raw-text field you could provide any of the valid `config
+formats`_.
+
+You have the option to encode your user-data using Base64. In order to do that
+you have to add the ``cloudinit-user-data`` field to the ``base64_fields``.
+The latter is a comma-separated field with all the meta fields whit base64
+encoded values.
+
+If your user-data does not need an internet connection you can create a `meta
+field`_ in the `server context`_ ``cloudinit-dsmode`` and set "local" as
+value.  If this field does not exist the default value is "net".
+
+
+.. _CloudSigma: http://cloudsigma.com/
+.. _server context: http://cloudsigma-docs.readthedocs.org/en/latest/server_context.html
+.. _meta field: http://cloudsigma-docs.readthedocs.org/en/latest/meta.html
+.. _config formats: http://cloudinit.readthedocs.org/en/latest/topics/format.html
+.. vi: textwidth=78
diff --git a/doc/rtd/topics/datasources/cloudstack.rst b/doc/rtd/topics/datasources/cloudstack.rst
new file mode 100644
index 00000000..04603d9c
--- /dev/null
+++ b/doc/rtd/topics/datasources/cloudstack.rst
@@ -0,0 +1,34 @@
+CloudStack
+==========
+
+`Apache CloudStack`_ expose user-data, meta-data, user password and account
+sshkey thru the Virtual-Router. For more details on meta-data and user-data,
+refer the `CloudStack Administrator Guide`_. 
+
+URLs to access user-data and meta-data from the Virtual Machine. Here 10.1.1.1
+is the Virtual Router IP:
+
+.. code:: bash
+
+    http://10.1.1.1/latest/user-data
+    http://10.1.1.1/latest/meta-data
+    http://10.1.1.1/latest/meta-data/{metadata type}
+
+Configuration
+-------------
+
+Apache CloudStack datasource can be configured as follows:
+
+.. code:: yaml
+
+    datasource:
+      CloudStack: {}
+      None: {}
+    datasource_list:
+      - CloudStack
+
+
+.. _Apache CloudStack: http://cloudstack.apache.org/
+.. _CloudStack Administrator Guide: http://docs.cloudstack.apache.org/projects/cloudstack-administration/en/latest/virtual_machines.html#user-data-and-meta-data
+
+.. vi: textwidth=78
diff --git a/doc/rtd/topics/datasources/configdrive.rst b/doc/rtd/topics/datasources/configdrive.rst
new file mode 100644
index 00000000..acdab6a2
--- /dev/null
+++ b/doc/rtd/topics/datasources/configdrive.rst
@@ -0,0 +1,129 @@
+Config Drive
+============
+
+The configuration drive datasource supports the `OpenStack`_ configuration
+drive disk.
+
+  See `the config drive extension`_ and `introduction`_ in the public
+  documentation for more information.
+
+By default, cloud-init does *always* consider this source to be a full-fledged
+datasource.  Instead, the typical behavior is to assume it is really only
+present to provide networking information.  Cloud-init will copy off the
+network information, apply it to the system, and then continue on.  The "full"
+datasource could then be found in the EC2 metadata service. If this is not the
+case then the files contained on the located drive must provide equivalents to
+what the EC2 metadata service would provide (which is typical of the version 2
+support listed below)
+
+Version 1
+---------
+
+The following criteria are required to as a config drive:
+
+1. Must be formatted with `vfat`_ filesystem
+2. Must be a un-partitioned block device (/dev/vdb, not /dev/vdb1)
+3. Must contain *one* of the following files
+
+::
+
+  /etc/network/interfaces
+  /root/.ssh/authorized_keys
+  /meta.js
+
+``/etc/network/interfaces``
+
+    This file is laid down by nova in order to pass static networking
+    information to the guest.  Cloud-init will copy it off of the config-drive
+    and into /etc/network/interfaces (or convert it to RH format) as soon as
+    it can, and then attempt to bring up all network interfaces.
+
+``/root/.ssh/authorized_keys``
+
+    This file is laid down by nova, and contains the ssk keys that were
+    provided to nova on instance creation (nova-boot --key ....)
+
+``/meta.js``
+
+    meta.js is populated on the config-drive in response to the user passing
+    "meta flags" (nova boot --meta key=value ...). It is expected to be json
+    formatted.
+
+Version 2
+---------
+
+The following criteria are required to as a config drive:
+
+1. Must be formatted with `vfat`_ or `iso9660`_ filesystem
+   or have a *filesystem* label of **config-2**
+2. Must be a un-partitioned block device (/dev/vdb, not /dev/vdb1)
+3. The files that will typically be present in the config drive are:
+
+::
+
+  openstack/
+    - 2012-08-10/ or latest/ 
+      - meta_data.json
+      - user_data (not mandatory)
+    - content/
+      - 0000 (referenced content files)
+      - 0001
+      - ....
+  ec2
+    - latest/
+      - meta-data.json (not mandatory)
+
+Keys and values
+---------------
+
+Cloud-init's behavior can be modified by keys found in the meta.js (version 1
+only) file in the following ways.
+
+::
+
+   dsmode:  
+     values: local, net, pass
+     default: pass
+
+
+This is what indicates if configdrive is a final data source or not.
+By default it is 'pass', meaning this datasource should not be read.
+Set it to 'local' or 'net' to stop cloud-init from continuing on to
+search for other data sources after network config.
+
+The difference between 'local' and 'net' is that local will not require
+networking to be up before user-data actions (or boothooks) are run.
+
+::
+    
+   instance-id:
+     default: iid-dsconfigdrive
+     
+This is utilized as the metadata's instance-id.  It should generally
+be unique, as it is what is used to determine "is this a new instance".
+
+::
+
+   public-keys:
+     default: None
+  
+If present, these keys will be used as the public keys for the
+instance.  This value overrides the content in authorized_keys.
+
+Note: it is likely preferable to provide keys via user-data
+
+::
+    
+   user-data:
+     default: None
+     
+This provides cloud-init user-data. See :ref:`examples <yaml_examples>` for 
+what all can be present here.
+
+.. _OpenStack: http://www.openstack.org/
+.. _introduction: http://docs.openstack.org/trunk/openstack-compute/admin/content/config-drive.html
+.. _python-novaclient: https://github.com/openstack/python-novaclient
+.. _iso9660: https://en.wikipedia.org/wiki/ISO_9660
+.. _vfat: https://en.wikipedia.org/wiki/File_Allocation_Table
+.. _the config drive extension: http://docs.openstack.org/user-guide/content/config-drive.html
+.. vi: textwidth=78
diff --git a/doc/rtd/topics/datasources/digitalocean.rst b/doc/rtd/topics/datasources/digitalocean.rst
new file mode 100644
index 00000000..c6f5bc74
--- /dev/null
+++ b/doc/rtd/topics/datasources/digitalocean.rst
@@ -0,0 +1,28 @@
+Digital Ocean
+=============
+
+The `DigitalOcean`_ datasource consumes the content served from DigitalOcean's
+`metadata service`_.  This metadata service serves information about the
+running droplet via HTTP over the link local address 169.254.169.254.  The
+metadata API endpoints are fully described at
+`https://developers.digitalocean.com/metadata/
+<https://developers.digitalocean.com/metadata/>`_.
+
+Configuration
+-------------
+
+DigitalOcean's datasource can be configured as follows:
+
+  datasource:
+    DigitalOcean:
+      retries: 3
+      timeout: 2
+
+- *retries*: Determines the number of times to attempt to connect to the metadata service
+- *timeout*: Determines the timeout in seconds to wait for a response from the metadata service
+
+.. _DigitalOcean: http://digitalocean.com/
+.. _metadata service: https://developers.digitalocean.com/metadata/
+.. _Full documentation: https://developers.digitalocean.com/metadata/
+
+.. vi: textwidth=78
diff --git a/doc/rtd/topics/datasources/ec2.rst b/doc/rtd/topics/datasources/ec2.rst
new file mode 100644
index 00000000..4810c984
--- /dev/null
+++ b/doc/rtd/topics/datasources/ec2.rst
@@ -0,0 +1,61 @@
+Amazon EC2
+==========
+
+The EC2 datasource is the oldest and most widely used datasource that
+cloud-init supports. This datasource interacts with a *magic* ip that is
+provided to the instance by the cloud provider. Typically this ip is
+``169.254.169.254`` of which at this ip a http server is provided to the
+instance so that the instance can make calls to get instance userdata and
+instance metadata.
+
+Metadata is accessible via the following URL:
+
+::
+    
+    GET http://169.254.169.254/2009-04-04/meta-data/
+    ami-id
+    ami-launch-index
+    ami-manifest-path
+    block-device-mapping/
+    hostname
+    instance-id
+    instance-type
+    local-hostname
+    local-ipv4
+    placement/
+    public-hostname
+    public-ipv4
+    public-keys/
+    reservation-id
+    security-groups
+
+Userdata is accessible via the following URL:
+
+::
+    
+    GET http://169.254.169.254/2009-04-04/user-data
+    1234,fred,reboot,true | 4512,jimbo, | 173,,,
+
+Note that there are multiple versions of this data provided, cloud-init
+by default uses **2009-04-04** but newer versions can be supported with
+relative ease (newer versions have more data exposed, while maintaining
+backward compatibility with the previous versions). 
+
+To see which versions are supported from your cloud provider use the following URL:
+
+::
+    
+    GET http://169.254.169.254/
+    1.0
+    2007-01-19
+    2007-03-01
+    2007-08-29
+    2007-10-10
+    2007-12-15
+    2008-02-01
+    2008-09-01
+    2009-04-04
+    ...
+    latest
+
+.. vi: textwidth=78
diff --git a/doc/rtd/topics/datasources/fallback.rst b/doc/rtd/topics/datasources/fallback.rst
new file mode 100644
index 00000000..1eb01dd0
--- /dev/null
+++ b/doc/rtd/topics/datasources/fallback.rst
@@ -0,0 +1,16 @@
+Fallback/None
+=============
+
+This is the fallback datasource when no other datasource can be selected. It
+is the equivalent of a empty datasource in that it provides a empty string as
+userdata and a empty dictionary as metadata. It is useful for testing as well
+as for when you do not have a need to have an actual datasource to meet your
+instance requirements (ie you just want to run modules that are not concerned
+with any external data). It is typically put at the end of the datasource
+search list so that if all other datasources are not matched, then this one
+will be so that the user is not left with an inaccessible instance.
+
+**Note:** the instance id that this datasource provides is
+``iid-datasource-none``.
+
+.. vi: textwidth=78
diff --git a/doc/rtd/topics/datasources/maas.rst b/doc/rtd/topics/datasources/maas.rst
new file mode 100644
index 00000000..f495dd4b
--- /dev/null
+++ b/doc/rtd/topics/datasources/maas.rst
@@ -0,0 +1,8 @@
+MAAS
+====
+
+*TODO*
+
+For now see: http://maas.ubuntu.com/
+
+
diff --git a/doc/rtd/topics/datasources/nocloud.rst b/doc/rtd/topics/datasources/nocloud.rst
new file mode 100644
index 00000000..b9ab5f11
--- /dev/null
+++ b/doc/rtd/topics/datasources/nocloud.rst
@@ -0,0 +1,75 @@
+NoCloud
+=======
+
+The data source ``NoCloud`` allows the user to provide user-data and meta-data
+to the instance without running a network service (or even without having a
+network at all).
+
+You can provide meta-data and user-data to a local vm boot via files on a
+`vfat`_ or `iso9660`_ filesystem. The filesystem volume label must be
+``cidata``.
+
+These user-data and meta-data files are expected to be in the following format.
+
+::
+
+  /user-data
+  /meta-data
+
+Basically, user-data is simply user-data and meta-data is a yaml formatted file
+representing what you'd find in the EC2 metadata service.
+
+Given a disk ubuntu 12.04 cloud image in 'disk.img', you can create a
+sufficient disk by following the example below.
+
+::
+    
+    ## create user-data and meta-data files that will be used
+    ## to modify image on first boot
+    $ { echo instance-id: iid-local01; echo local-hostname: cloudimg; } > meta-data
+    
+    $ printf "#cloud-config\npassword: passw0rd\nchpasswd: { expire: False }\nssh_pwauth: True\n" > user-data
+    
+    ## create a disk to attach with some user-data and meta-data
+    $ genisoimage  -output seed.iso -volid cidata -joliet -rock user-data meta-data
+    
+    ## alternatively, create a vfat filesystem with same files
+    ## $ truncate --size 2M seed.img
+    ## $ mkfs.vfat -n cidata seed.img
+    ## $ mcopy -oi seed.img user-data meta-data ::
+    
+    ## create a new qcow image to boot, backed by your original image
+    $ qemu-img create -f qcow2 -b disk.img boot-disk.img
+    
+    ## boot the image and login as 'ubuntu' with password 'passw0rd'
+    ## note, passw0rd was set as password through the user-data above,
+    ## there is no password set on these images.
+    $ kvm -m 256 \
+       -net nic -net user,hostfwd=tcp::2222-:22 \
+       -drive file=boot-disk.img,if=virtio \
+       -drive file=seed.iso,if=virtio
+
+**Note:** that the instance-id provided (``iid-local01`` above) is what is used
+to determine if this is "first boot".  So if you are making updates to
+user-data you will also have to change that, or start the disk fresh.
+
+Also, you can inject an ``/etc/network/interfaces`` file by providing the
+content for that file in the ``network-interfaces`` field of metadata.  
+
+Example metadata:
+
+::
+    
+    instance-id: iid-abcdefg
+    network-interfaces: |
+      iface eth0 inet static
+      address 192.168.1.10
+      network 192.168.1.0
+      netmask 255.255.255.0
+      broadcast 192.168.1.255
+      gateway 192.168.1.254
+    hostname: myhost
+
+.. _iso9660: https://en.wikipedia.org/wiki/ISO_9660
+.. _vfat: https://en.wikipedia.org/wiki/File_Allocation_Table
+.. vi: textwidth=78
diff --git a/doc/rtd/topics/datasources/opennebula.rst b/doc/rtd/topics/datasources/opennebula.rst
new file mode 100644
index 00000000..1b90a9c7
--- /dev/null
+++ b/doc/rtd/topics/datasources/opennebula.rst
@@ -0,0 +1,146 @@
+OpenNebula
+==========
+
+The `OpenNebula`_ (ON) datasource supports the contextualization disk.
+
+  See `contextualization overview`_, `contextualizing VMs`_ and
+  `network configuration`_ in the public documentation for
+  more information.
+
+OpenNebula's virtual machines are contextualized (parametrized) by
+CD-ROM image, which contains a shell script *context.sh* with
+custom variables defined on virtual machine start. There are no
+fixed contextualization variables, but the datasource accepts
+many used and recommended across the documentation.
+
+Datasource configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Datasource accepts following configuration options.
+
+::
+    
+    dsmode:
+      values: local, net, disabled
+      default: net
+
+Tells if this datasource will be processed in 'local' (pre-networking) or
+'net' (post-networking) stage or even completely 'disabled'.
+
+::
+    
+    parseuser:
+      default: nobody
+
+Unprivileged system user used for contextualization script
+processing.
+
+Contextualization disk
+~~~~~~~~~~~~~~~~~~~~~~
+
+The following criteria are required:
+
+1. Must be formatted with `iso9660`_ filesystem
+   or have a *filesystem* label of **CONTEXT** or **CDROM**
+2. Must contain file *context.sh* with contextualization variables.
+   File is generated by OpenNebula, it has a KEY='VALUE' format and
+   can be easily read by bash 
+
+Contextualization variables
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There are no fixed contextualization variables in OpenNebula, no standard.
+Following variables were found on various places and revisions of
+the OpenNebula documentation. Where multiple similar variables are
+specified, only first found is taken.
+
+::
+    
+    DSMODE
+
+Datasource mode configuration override. Values: local, net, disabled.
+
+::
+
+    DNS
+    ETH<x>_IP
+    ETH<x>_NETWORK
+    ETH<x>_MASK
+    ETH<x>_GATEWAY
+    ETH<x>_DOMAIN
+    ETH<x>_DNS
+
+Static `network configuration`_.
+
+::
+    
+    HOSTNAME
+
+Instance hostname.
+
+::
+    
+    PUBLIC_IP
+    IP_PUBLIC
+    ETH0_IP
+
+If no hostname has been specified, cloud-init will try to create hostname
+from instance's IP address in 'local' dsmode. In 'net' dsmode, cloud-init 
+tries to resolve one of its IP addresses to get hostname.
+
+::
+    
+    SSH_KEY
+    SSH_PUBLIC_KEY
+
+One or multiple SSH keys (separated by newlines) can be specified.
+
+::
+    
+    USER_DATA
+    USERDATA
+
+cloud-init user data.
+
+Example configuration
+~~~~~~~~~~~~~~~~~~~~~
+
+This example cloud-init configuration (*cloud.cfg*) enables
+OpenNebula datasource only in 'net' mode.
+
+::
+    
+    disable_ec2_metadata: True
+    datasource_list: ['OpenNebula']
+    datasource:
+      OpenNebula:
+        dsmode: net
+        parseuser: nobody
+
+Example VM's context section
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+    
+    CONTEXT=[
+      PUBLIC_IP="$NIC[IP]",
+      SSH_KEY="$USER[SSH_KEY] 
+    $USER[SSH_KEY1] 
+    $USER[SSH_KEY2] ",
+      USER_DATA="#cloud-config
+    # see https://help.ubuntu.com/community/CloudInit
+    
+    packages: []
+    
+    mounts:
+    - [vdc,none,swap,sw,0,0]
+    runcmd:
+    - echo 'Instance has been configured by cloud-init.' | wall
+    " ]
+
+.. _OpenNebula: http://opennebula.org/
+.. _contextualization overview: http://opennebula.org/documentation:documentation:context_overview
+.. _contextualizing VMs: http://opennebula.org/documentation:documentation:cong
+.. _network configuration: http://opennebula.org/documentation:documentation:cong#network_configuration
+.. _iso9660: https://en.wikipedia.org/wiki/ISO_9660
+.. vi: textwidth=78
diff --git a/doc/rtd/topics/datasources/openstack.rst b/doc/rtd/topics/datasources/openstack.rst
new file mode 100644
index 00000000..ea47ea85
--- /dev/null
+++ b/doc/rtd/topics/datasources/openstack.rst
@@ -0,0 +1,28 @@
+OpenStack
+=========
+
+*TODO*
+
+Vendor Data
+-----------
+
+The OpenStack metadata server can be configured to serve up vendor data
+which is available to all instances for consumption.  OpenStack vendor
+data is, generally, a JSON object.
+
+cloud-init will look for configuration in the ``cloud-init`` attribute
+of the vendor data JSON object. cloud-init processes this configuration
+using the same handlers as user data, so any formats that work for user
+data should work for vendor data.
+
+For example, configuring the following as vendor data in OpenStack would
+upgrade packages and install ``htop`` on all instances:
+
+.. sourcecode:: json
+
+  {"cloud-init": "#cloud-config\npackage_upgrade: True\npackages:\n - htop"}
+
+For more general information about how cloud-init handles vendor data,
+including how it can be disabled by users on instances, see `Vendor Data`_.
+
+.. vi: textwidth=78
diff --git a/doc/rtd/topics/datasources/ovf.rst b/doc/rtd/topics/datasources/ovf.rst
new file mode 100644
index 00000000..a0770332
--- /dev/null
+++ b/doc/rtd/topics/datasources/ovf.rst
@@ -0,0 +1,12 @@
+OVF
+===
+
+The OVF Datasource provides a datasource for reading data from
+on an `Open Virtualization Format
+<https://en.wikipedia.org/wiki/Open_Virtualization_Format>`_ ISO
+transport.
+
+For further information see a full working example in cloud-init's
+source code tree in doc/sources/ovf
+
+.. vi: textwidth=78
diff --git a/doc/rtd/topics/datasources/smartos.rst b/doc/rtd/topics/datasources/smartos.rst
new file mode 100644
index 00000000..a1e1542b
--- /dev/null
+++ b/doc/rtd/topics/datasources/smartos.rst
@@ -0,0 +1,164 @@
+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.<timestamp>. <timestamp> 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.<timestamp>.
+    - <timestamp> 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 #!<executable>), 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:
+
+.. code:: yaml
+
+  #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
+
+.. code:: yaml
+
+  #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-<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.
+
+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.
+
+.. vi: textwidth=78