linux_feature

Guest Contextualization Features

The OpenNebula contextualization process plays a pivotal role in configuring various aspects of the VM guest during boot time. Leveraging information from the VM within the OpenNebula cloud, this package ensures streamlined integration. 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 both added using the CLI to the template or using Sunstone Template wizard. Here is an example of the context section using 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. To do this configuration it injects the network information in the contextualization section. This is done with option NETWORK = "YES":

CONTEXT = [
  NETWORK = "YES"
]

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

Important

VM NIC and Virtual Networks can define multiple attributes that are passed through CONTEXT to the guest OS, like GATEWAY, DNS or METRIC, please check the complete list here for setting up the guest interfaces.

Warning

When having several NICs with GATEWAY defined, it is important to have different METRIC attributes on each. If this attribute is missing, they will default to the same value and that could cause issues with certain NETCFG_TYPE network configuration types.

Guest Network Management Service

The context scripts provide flexibility in selecting the guest network management service, responsible for assigning IP addresses, configuring routes, and initializing interfaces within the guest OS. By setting the context variable NETCFG_TYPE, users can choose from various network configuration types.

Important

The default behavior, when NETCFG_TYPE is empty, involves autodetection to determine the most suitable configuration type for the platform. Only set the configuration type if you have specific requirements for a given type.

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 attribute METHOD for IPv4 and IP6_METHOD for IPv6. The supported methods include:

For IPv4:

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

For 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

(other platforms not listed above are not supported for using 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

One of the other very important things you have to configure is user credentials to connect to the newly created Virtual Machine. For linux base images we recommend to use SSH public key authentication and using it with OpenNebula is very convenient.

Begin by adding your SSH public key (or keys) to your OpenNebula user configuration. This can be accomplished through the Settings section on the web interface or via the command line interface.

Next, in the Virtual Machine Template, include the following option so the VM will inherit the SSH public key of the user who initiated them :

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

Additionally, the options USERNAME and PASSWORD can be used 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.

Execute 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 installed in the base image, accompanied by the appropriate shebang line.

In the following example, a bash script will be executed 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, utilize the START_SCRIPT_BASE64 option, which accepts a base64 encoded string that will be decoded before writing the temporary script file.

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 configuring additional guest aspects:

• 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 offers a centralized service to share data between Virtual Machines and the main daemon. You can tailor the interaction between the onegate client in the VM and the onegate server by using several parameters in the CONTEXT section

• TOKEN: When set to YES it adds a security for the VM to authenticate in 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 will report the VM to be READY to the onegate client. This is useful for the oneflow service to determine when a VM is RUNNING as the VM might be RUNNING from the perspective of the hypervisor, but still booting and or configuring important services, like the one-context daemon.
• READY_SCRIPT: When the variable is defined, the REPORT_READY functionality will only be used after the contents of the variable are succesfully executed. It is useful to customize your appliance readiness. For example READY_SCRIPT="nc -vz localhost 8000" will only return 0 if the port 8000 is up.
• READY_SCRIPT_PATH: Similar to READY_SCRIPT but the script exists in the Guest filesystem and its path is what needs to be defined on 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 to wait between each attempt. Defaults to 1 second.

Re-contextualization a VM Guest

Recontextualization is triggerd by udev on 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.