Guest Contextualization Features

The OpenNebula contextualization process plays a pivotal role in configuring various aspects of the guest VM at boot time. Contextualization packages ensure streamlined integration of the VM in the OpenNebula cloud, by leveraging information from the VM. The OpenNebula contextualization process enables users to:

• Configure guest networking and hostname settings.
• Set up user credentials for seamless VM access.
• Define the system timezone.
• Resize disk partitions as needed.
• Execute custom actions during boot.

Configuration parameters are passed to the contextualization packages through the CONTEXT attribute of the virtual machine. The most common attributes are network configuration, user credentials or startup scripts. These parameters can be added to the template by using the CLI or the Sunstone Template Wizard. Below is an example of the context section in the CLI:

    CONTEXT = [
        TOKEN = "YES",
        NETWORK = "YES",
        SSH_PUBLIC_KEY = "$USER[SSH_PUBLIC_KEY]",
        START_SCRIPT = "yum install -y ntpdate"
    ]

Network Configuration

OpenNebula does not rely on a DHCP server to configure networking in the Virtual Machines. Instead, it injects the network information in the contextualization section. This is activated by the option NETWORK = "YES":

CONTEXT = [
  NETWORK = "YES"
]

When OpenNebula finds this option, it adds the IP information for each of the configured network interfaces, plus extra information that resides in the Virtual Network template such as DNS, gateway and network mask.

[!IMPORTANT] VM NIC and Virtual Networks can define multiple attributes that are passed through CONTEXT to the guest OS, such as GATEWAY, DNS or METRIC. To set up the guest interfaces, please check the documentation for the complete list.

[!WARNING] When having several NICs with GATEWAY defined, it is important to define different METRIC values for each. If this attribute is missing, the NICs will default to the same value, which could cause issues with certain NETCFG_TYPE network configuration types.

Guest Network Management Service

In the guest OS, the network management service is responsible for assigning IP addresses, configuring routes, and initializing interfaces. The contextualization package contains scripts that allow you to select the guest network management service, by setting the value of the context variable NETCFG_TYPE.

[!IMPORTANT] Leave the value of NETCFG_TYPE empty unless you require a specific network configuration type. If NETCFG_TYPE is empty, the default behavior is to perform autodetection to determine the most suitable configuration type for the platform.

The available network configuration types include:

• bsd: Configures FreeBSD network settings.
• interfaces: Sets up Debian-style configurations in /etc/network/interfaces.
• netplan: For Netplan configurations. Users can further specify the renderer via the NETCFG_NETPLAN_RENDERER context variable, choosing from:
  • Empty or networkd (default) for systemd-network.
  • NetworkManager for NetworkManager.
• networkd: Configures systemd-networkd.
• nm: Manages NetworkManager.
• scripts: Sets up legacy Red Hat-style configurations via /etc/sysconfig/network-scripts/ifcfg-ethX files.

Users can also customize the method for configuring interface IP addresses through the NIC attributes METHOD (for IPv4) and IP6_METHOD (for IPv6). The supported methods include:

METHOD - IPv4:

• Empty or static: Assigns static addresses based on context variables.
• dhcp: Uses DHCPv4.
• skip: Bypasses IPv4 configuration.

IP6_METHOD - IPv6:

• Empty or static: Assigns static addresses based on context variables.
• auto: Enables SLAAC (Stateless Address Autoconfiguration).
• dhcp: Facilitates SLAAC and DHCPv6.
• disable: Turns off IPv6 within the guest.
• skip: Skips IPv6 configuration.

It's important to note that selectable configuration types and IP configuration methods are limited to the following specific platforms:

Platform	Network Type (NETCFG_TYPE)
Alpine	interfaces
ALT	networkd, nm
Amazon Linux	scripts
Debian 12	netplan, networkd, interfaces, nm
Debian 11-	interfaces, netplan, nm, networkd
Devuan	interfaces, netplan, nm, networkd
FreeBSD	bsd
openSUSE, SLES, SLED	scripts
RHEL-like 8 (CentOS, Oracle/Rocky/AlmaLinux)	nm, scripts, networkd
RHEL-like 9 (CentOS Stream 9, Oracle/Rocky/AlmaLinux)	nm, networkd
Ubuntu	netplan, networkd, interfaces, nm

[!IMPORTANT] Platforms not listed above do not support NETCFG_TYPE nor METHOD/IP6_METHOD.

Known Issues

• Alpine Linux: IP6_METHOD=dhcp runs DHCPv4 client instead of DHCPv6,
• Alt Linux: DEV_PREFIX=vd is the only DEV_PREFIX that results in a booting OS.
• Debian/Ubuntu: NETCFG_TYPE=netplan with NetworkManager might not configure IPv6 SLAAC (IP6_METHOD=auto) for hot-plugged interfaces,
• Ubuntu 20.04: might trigger DHCPv6 with IP6_METHOD=auto
  • on NETCFG_TYPE=netplan with networkd,
  • on NETCFG_TYPE=networkd.

User Credentials

User credentials are an essential configuration item. You will need these credentials to connect to the newly-created Virtual Machine. For Linux base images we recommend using public SSH authentication, which OpenNebula makes very convenient to use.

To add SSH user credentials, begin by adding your SSH public key(s) to your OpenNebula user configuration. You can add SSH keys using the Sunstone web UI or using the CLI.

Next, ensure that the Virtual Machine will inherit the SSH key of the user that initiated it. In the VM template, include the following option:

CONTEXT = [
    SSH_PUBLIC_KEY = "$USER[SSH_PUBLIC_KEY]"
]

You can also use the options USERNAME and PASSWORD to create an initial administrator and set their password:

CONTEXT = [
    USERNAME = "Administrator",
    PASSWORD = "VeryComplexPassw0rd"
]

[!NOTE] This password is encrypted both within the virtual machine and in the virtual machine template.

Running Scripts on Boot

To execute commands during boot you can use the START_SCRIPT option. This option creates and executes a new file containing the specified value. The scripting language used can be any language installed in the base image, invoked by the appropriate shebang line.

In the below example, a Bash script is called to install the ntpdate package and set the time:

CONTEXT = [
    START_SCRIPT = "#!/bin/bash
yum update
yum install -y ntpdate
ntpdate 0.pool.ntp.org"
]

For more intricate scripts, use the START_SCRIPT_BASE64 option, which accepts a base64-encoded string that will be decoded before writing the temporary script file.

Cloud-config scripts

In addition to the START_SCRIPT feature previously described, you can execute cloud-config scripts at boot time by specifying them in the USER_DATA parameter within the VM CONTEXT. Similar to the START_SCRIPT feature, you can encode the cloud-config script in base64 by setting the USER_DATA_ENCODING=base64 parameter in the CONTEXT block.

Currently, only the following cloud-init modules are supported:

• write_files
• runcmd

This feature is compatible with cloud-init's OpenNebula datasource contextualization disk USER_DATA and USERDATA variables.

[!NOTE] The cloud-init script will be executed just before the START_SCRIPT execution.

[!NOTE] The cloud-init script will be executed only once at VM boot time after enabling networking, regardless of any recontextualization. If you want to execute the cloud-config script again, you need to delete the /var/lib/one-context/cloudinit/cloudinit-boot-finished file manually and trigger a recontextualization.

File System Configuration

OpenNebula enables resizing VM disk images before boot, allowing users to provide lightweight base images. In this case you can instruct the context packages to grow the file systems to match the new disk size. In particular you can add to the CONTEXT section the following options:

• GROW_ROOTFS: Automatically grows the root file system.
• GROW_FS: Specifies mountpoints to grow (e.g., /mnt/disk /data).

Also, you can skip the automatic mounting of any detected swap device with IGNORE_SWAP. Note that this does not affect swap defined in /etc/fstab.

Other System Configuration

The following CONTEXT attributes allow for defining additional configuration on the guest:

• TIMEZONE: Specifies the time zone to set, matching the zone file name relative to /usr/share/zoneinfo/ (e.g., US/Central).
• SET_HOSTNAME: Sets the VM hostname. Alternatively, add DNS_HOSTNAME = "YES" to set the VM hostname to the reverse DNS name from the first IP.

OneGate Client

OpenNebula includes OneGate, a centralized service that enables sharing of data between Virtual Machines and the main OpenNebula daemon. You can tailor the interaction between the OpenNebula OneGate server and the OneGate client in the VM, by using the below parameters in the CONTEXT section:

• TOKEN: When set to YES, adds a security token for the VM to authenticate to the OneGate server.
• ONEGATE_ENDPOINT: The URL where the OneGate server is running. OpenNebula will automatically add this variable if TOKEN=YES is set. Defaults to http://169.254.16.9:5030. The value is loaded from /etc/one/oned.conf.
• REPORT_READY: When set to YES the OneGate client in the VM will report to the OneGate server that the VM is READY. This is useful for the OneFlow service to ensure that a VM has finished booting and is effectively in the RUNNING state.
• READY_SCRIPT: When this variable is defined, the REPORT_READY functionality will only be used after the contents of the variable are successfully executed. This is useful to customize the desired READY state for the appliance. For example, READY_SCRIPT="nc -vz localhost 8000" will only return 0 if port 8000 is up.
• READY_SCRIPT_PATH: Similar to READY_SCRIPT, but the script exists in the Guest filesystem and its path must be defined in the CONTEXT section. For example READY_SCRIPT_PATH=/usr/bin/echo.
• RETRY_COUNT: Amount of attempts to try REPORT_READY. Defaults to 3.
• RETRY_INTERVAL: How long to wait between each attempt. Defaults to 1 second.

Recontextualization of a VM Guest

Recontextualization is triggered by udev on the following events:

Event	Service started
Network interface add/remove	one-context-reconfigure-delayed
CDROM changed	one-context-reconfigure
Disk changed or hot-attached	one-context-force

See more details in udev rules for various systems.