1 files changed, 151 insertions, 0 deletions
diff --git a/doc/rtd/reference/datasources/opennebula.rst b/doc/rtd/reference/datasources/opennebula.rst
new file mode 100644
index 00000000..2ad9d5c3
--- /dev/null
+++ b/doc/rtd/reference/datasources/opennebula.rst
@@ -0,0 +1,151 @@
+.. _datasource_opennebula:
+
+OpenNebula
+**********
+
+The `OpenNebula`_ (ON) datasource supports the contextualisation disk.
+
+.. THESE LINKS ARE BROKEN
+..  See `contextualization overview`_, `contextualizing VMs`_ and
+..  `network configuration`_ in the public documentation for
+.. more information.
+
+OpenNebula's virtual machines are contextualised (parametrised) by
+CD-ROM image, which contains a shell script :file:`context.sh`, with
+custom variables defined on virtual machine start. There are no
+fixed contextualisation variables, but the datasource accepts
+many used and recommended across the documentation.
+
+Datasource configuration
+========================
+
+Datasource accepts the following configuration options: ::
+
+    dsmode:
+      values: local, net, disabled
+      default: net
+
+These specify whether the datasource will be processed in ``local``
+(pre-networking) stage, ``net`` (post-networking) stage or be ``disabled``.
+
+::
+
+    parseuser:
+      default: nobody
+
+Unprivileged system user used for contextualisation script processing.
+
+Contextualisation 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 the file :file:`context.sh` with contextualisation variables.
+   The file is generated by OpenNebula and has a ``KEY='VALUE'`` format that
+   can be easily read by bash.
+
+Contextualisation variables
+===========================
+
+There are no fixed or standard contextualisation variables in OpenNebula.
+The following variables were found in various places and in revisions of
+the OpenNebula documentation. Where multiple similar variables are
+specified, only the one found first is taken.
+
+* ``DSMODE``: Datasource mode configuration override. Values are: ``local``,
+  ``net``, ``disabled``.
+
+::
+
+    DNS
+    ETH<x>_IP
+    ETH<x>_NETWORK
+    ETH<x>_MASK
+    ETH<x>_GATEWAY
+    ETH<x>_GATEWAY6
+    ETH<x>_DOMAIN
+    ETH<x>_DNS
+    ETH<x>_SEARCH_DOMAIN
+    ETH<x>_MTU
+    ETH<x>_IP6
+    ETH<x>_IP6_ULA
+    ETH<x>_IP6_PREFIX_LENGTH
+    ETH<x>_IP6_GATEWAY
+
+Static `network configuration`_.
+
+::
+
+    SET_HOSTNAME
+    HOSTNAME
+
+Instance hostname.
+
+::
+
+    PUBLIC_IP
+    IP_PUBLIC
+    ETH0_IP
+
+If no hostname has been specified, ``cloud-init`` will try to create a
+hostname from the instance's IP address in ``local`` dsmode. In ``net``
+dsmode, ``cloud-init`` tries to resolve one of its IP addresses to get
+the 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 (:file:`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
+============================
+
+.. code-block:: sh
+
+    CONTEXT=[
+      SSH_KEY="$USER[SSH_KEY]
+    $USER[SSH_KEY1]
+    $USER[SSH_KEY2]",
+      PUBLIC_IP="$NIC[IP]",
+      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