OpenNebula datasource documentation update.

2 files changed, 117 insertions, 66 deletions

diff --git a/doc/sources/opennebula/README b/doc/sources/opennebula/README
deleted file mode 100644
index 772a5b99..00000000
--- a/doc/sources/opennebula/README
+++ /dev/null
@@ -1,66 +0,0 @@
-The 'OpenNebula' DataSource supports the OpenNebula contextualization disk.
-
-The following criteria are required to be identified by
-DataSourceOpenNebula as contextualization disk:
-  * must be formatted with iso9660 filesystem or labeled as CDROM
-  * must be un-partitioned block device (/dev/vdb, not /dev/vdb1)
-  * must contain
-     * context.sh
-
-== Content of config-drive ==
-  * context.sh
-    This is the only mandatory file on context disk, the rest content depends
-    on contextualization parameter FILES and thus is optional. It's
-    a shell script defining all context parameters. This script is
-    processed by bash (/bin/bash) to simulate behaviour of common
-    OpenNebula context scripts. Processed variables are handed over
-    back to cloud-init for further processing.
-
-== Configuration ==
-Cloud-init's behaviour can be modified by context variables found
-in the context.sh file in the folowing ways (variable names are
-case-insensitive):
-  * dsmode:
-    values: local, net, disabled
-    default: None
-
-    Tells if this datasource will be processed in local (pre-networking) or
-    net (post-networking) stage or even completely disabled.
-
-  * ssh_key:
-    default: None
-    If present, these key(s) will be used as the public key(s) for
-    the instance. More keys can be specified in this single context
-    variable, but each key must be on it's own line. I.e. keys must
-    be separated by newlines.
-
-  * hostname:
-    default: None
-    Custom hostname for the instance.
-
-  * public_ip:
-    default: None
-    If hostname not specified, public_ip is used to DNS resolve hostname.
-
-  * 'user_data' or 'userdata':
-    default: None
-    This provides cloud-init user-data. See other documentation for what
-    all can be present here.
-
-== Example OpenNebula's Virtual Machine template ==
-
-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
-" ]
diff --git a/doc/sources/opennebula/README.rst b/doc/sources/opennebula/README.rst
new file mode 100644
index 00000000..d4c3dc39
--- /dev/null
+++ b/doc/sources/opennebula/README.rst
@@ -0,0 +1,117 @@
+The `OpenNebula`_ DataSource supports the OpenNebula 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 data, 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 OpenNebula's 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'.
+
+Contextualization disk
+~~~~~~~~~~~~~~~~~~~~~~
+
+The following criteria are required:
+
+1. Must be formatted with `iso9660`_ fs. or have fs. label of **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 shell script.
+
+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 
+try 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 OpenNebula's Virtual Machine template
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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