.. _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