.. _datasource_opennebula:

OpenNebula
**********

The `OpenNebula`_ (ON) datasource supports the contextualization 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 contextualized (parametrized) by
CD-ROM image, which contains a shell script :file:`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
========================

The 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 contextualization 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.

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

* ``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 the
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: https://docs.opennebula.io/
.. _iso9660: https://en.wikipedia.org/wiki/ISO_9660